Introduction
A Unity REST Catalog refers to an API-based implementation that acts as a central metadata management service, often associated with distributed data processing and data lake architectures. It provides a unified interface to manage and query metadata for different data assets like databases, tables, schemas, and files stored across multiple storage systems.
The api are in beta state and expected to change.
Authentication Using Bearer Token
Required Purpose: To work with the API, you must use an IBM Cloud Pak for Data API key (platform API key or instance API key), or IBM Cloud Pak for Data authorization token (platform token or instance token). The API key or token is used to determine the actions that a user or service ID has access to when they use the API.
You can generate an API key or authorization token for an authenticated user by using the Cloud Pak for Data APIs. For more information, see Generating an authorization token or API key.
To use the API, add a valid API key or token to the HTTP Authorization request header. For token, -H 'Authorization: Bearer {TOKEN}'.
curl -H "Authorization: Bearer <token>" "https://<cpd_instance_route>/<endpoint>"
Authentication Using Basic Auth
Use CPD UI Login/password and generate the base64 encoding of <u:p> using command template
To retrieve your access token:
echo -n "<ui_username>:<ui_password>" | base64
Header to be used in the API:
--header 'Authorization: Basic YWRtaW46V1Vrc3d3bGt1blpF'
Sample API for get schemas unity api:
curl -k -X GET "https://ibm-lh-lakehouse-mds-rest-svc-cpd-instance.apps.enginecluster-yucca.cp.fyre.ibm.com/api/2.1/unity-catalog/schemas?catalog_name=hive" --header "Authorization: Basic YWRtaW46V1Vrc3d3bGt1blpF"
Error handling
This API uses standard HTTP response codes to indicate whether a method completed successfully. A 200 response indicates success. A 400 type response indicates a failure, and a 500 type response indicates an internal system error.
| HTTP Error Code | Description | Recovery |
|---|---|---|
200 |
Success | The request was successful. |
400 |
Bad Request | The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request. |
401 |
Unauthorized | You are not authorized to make this request. Log in to IBM Cloud and try again. If this error persists, contact the account owner to check your permissions. |
404 |
Not Found | The requested resource could not be found. |
500 |
Internal Server Error | Your request could not be processed. Wait a few minutes and try again. |
Methods
Request
Create catalog
{
"name": "catalog1",
"comment": "My new Catalog",
"properties": {
"storageName": "ibm_bucket",
"catalogType": "iceberg"
}
}Name of catalog.
Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^\s*(\{.*\}|\[.*\])\s*$A map of key-value properties attached to the securable.
User-provided free-form text description.
Possible values: 1 ≤ length ≤ 100000, Value must match regular expression
^[a-zA-Z0-9]*$
curl -X POST -H "accept: application/json" -H "Authorization: ••••••" -H "Content-Type: application/json" -d '{"name":"catalog1" ,"comment":"My new Catalog" ,"properties": {"storageName":"ibm_bucket" ,"catalogType":"iceberg" } }' "https://ibm-lh-lakehouse-mds-rest-cpd-instance.apps.enginecluster-fipsmds02.cp.fyre.ibm.com/api/2.1/unity-catalog/catalogs"
Response
Catalog Info
Name of catalog.
Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-zA-Z0-9]*$User-provided free-form text description.
Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^\s*(\{.*\}|\[.*\])\s*$A map of key-value properties attached to the securable.
Username of current owner of catalog.
Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-zA-Z0-9]*$Time at which this catalog was created, in epoch milliseconds.
Possible values: 0 ≤ value ≤ 1000000000000000
Username of catalog creator.
Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-zA-Z0-9]*$Time at which this catalog was last modified, in epoch milliseconds.
Possible values: 0 ≤ value ≤ 1000000000000000
Username of user who last modified catalog.
Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-zA-Z0-9]*$Unique identifier for the catalog.
Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-zA-Z0-9-_]*$
Status Code
The new catalog was successfully created.
Bad Request
Unauthorized
Not found
InternalServerError
{ "name": "catalog1", "comment": "My new Catalog", "properties": { "storageName": "ibm_bucket", "catalogType": "iceberg" }, "created_at": 1747292330, "updated_at": 0, "id": "0b8c015a-46f8-4778-8092-da84f9553100", "owner": "admin", "created_by": "admin", "updated_by": "null" }{ "error-code": 400, "message": "", "stack-trace": null, "type": "google.rpc.ErrorInfo", "reason": null, "metadata": {} }{ "error-code": 401, "message": "", "stack-trace": null, "type": "google.rpc.ErrorInfo", "reason": null, "metadata": {} }{ "error-code": 404, "message": "", "stack-trace": null, "type": "google.rpc.ErrorInfo", "reason": null, "metadata": {} }{ "error-code": 500, "message": "InternalServerError", "stack-trace": null, "type": "google.rpc.ErrorInfo", "reason": null, "metadata": {} }
List catalogs
Lists the available catalogs. There is no guarantee of a specific ordering of the elements in the list.
GET /catalogs
Request
Query Parameters
Opaque pagination token to go to next page based on previous query.
Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-zA-Z0-9]*$Maximum number of catalogs to return.
- when set to a value greater than 0, the page length is the minimum of this value and a server configured value;
- when set to 0, the page length is set to a server configured value;
- when set to a value less than 0, an invalid parameter error is returned;
Possible values: 0 ≤ value ≤ 1000000
curl -X GET -H "accept: application/json" -H "Authorization: ••••••" -H "Content-Type: application/json" "https://ibm-lh-lakehouse-mds-rest-cpd-instance.apps.enginecluster-fipsmds02.cp.fyre.ibm.com/api/2.1/unity-catalog/catalogs"
Response
List of catalogs
An array of catalog information objects.
Possible values: 0 ≤ number of items ≤ 1000000000
Opaque token to retrieve the next page of results. Absent if there are no more pages. page_token should be set to this value for the next request (for the next page of results).
Possible values: 1 ≤ length ≤ 2000000, Value must match regular expression
^[a-zA-Z0-9]*$
Status Code
The catalog list was successfully retrieved.
Bad Request
Unauthorized
Not found
InternalServerError
{ "catalogs": [ { "name": "catalog1", "comment": "", "properties": { "catalogType": "iceberg", "storageName": "ibm_bucket" }, "created_at": 1747298641, "updated_at": 0, "id": "da351865-e55c-48fd-bced-a75b674dd6a8", "owner": "admin", "created_by": "admin", "updated_by": null } ] }{ "error-code": 400, "message": "", "stack-trace": null, "type": "google.rpc.ErrorInfo", "reason": null, "metadata": {} }{ "error-code": 401, "message": "", "stack-trace": null, "type": "google.rpc.ErrorInfo", "reason": null, "metadata": {} }{ "error-code": 404, "message": "", "stack-trace": null, "type": "google.rpc.ErrorInfo", "reason": null, "metadata": {} }{ "error-code": 500, "message": "InternalServerError", "stack-trace": null, "type": "google.rpc.ErrorInfo", "reason": null, "metadata": {} }
Request
Path Parameters
The name of the catalog.
Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-zA-Z0-9]*$
curl -X GET -H "accept: application/json" -H "Authorization: ••••••" -H "Content-Type: application/json" "https://ibm-lh-lakehouse-mds-rest-cpd-instance.apps.enginecluster-fipsmds02.cp.fyre.ibm.com/api/2.1/unity-catalog/catalogs/catalog1"
Response
Catalog Info
Name of catalog.
Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-zA-Z0-9]*$User-provided free-form text description.
Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^\s*(\{.*\}|\[.*\])\s*$A map of key-value properties attached to the securable.
Username of current owner of catalog.
Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-zA-Z0-9]*$Time at which this catalog was created, in epoch milliseconds.
Possible values: 0 ≤ value ≤ 1000000000000000
Username of catalog creator.
Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-zA-Z0-9]*$Time at which this catalog was last modified, in epoch milliseconds.
Possible values: 0 ≤ value ≤ 1000000000000000
Username of user who last modified catalog.
Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-zA-Z0-9]*$Unique identifier for the catalog.
Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-zA-Z0-9-_]*$
Status Code
The catalog was successfully retrieved.
Bad Request
Unauthorized
Not found
InternalServerError
{ "name": "catalog1", "comment": "", "properties": { "catalogType": "iceberg", "storageName": "ibm_bucket" }, "created_at": 1747298641, "updated_at": 0, "id": "da351865-e55c-48fd-bced-a75b674dd6a8", "owner": "admin", "created_by": "admin", "updated_by": null }{ "error-code": 400, "message": "", "stack-trace": null, "type": "google.rpc.ErrorInfo", "reason": null, "metadata": {} }{ "error-code": 401, "message": "", "stack-trace": null, "type": "google.rpc.ErrorInfo", "reason": null, "metadata": {} }{ "error-code": 404, "message": "", "stack-trace": null, "type": "google.rpc.ErrorInfo", "reason": null, "metadata": {} }{ "error-code": 500, "message": "InternalServerError", "stack-trace": null, "type": "google.rpc.ErrorInfo", "reason": null, "metadata": {} }
Request
Path Parameters
The name of the catalog.
Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-zA-Z0-9]*$
Query Parameters
Force deletion even if the catalog is not empty.
curl -X DELETE -H "accept: application/json" -H "Authorization: ••••••" -H "Content-Type: application/json" "https://ibm-lh-lakehouse-mds-rest-cpd-instance.apps.enginecluster-fipsmds02.cp.fyre.ibm.com/api/2.1/unity-catalog/catalogs/catalog1?force=true"
Response
Delete Catalog Response
Status Code
The catalog was successfully deleted.
Bad Request
Unauthorized
Not found
InternalServerError
catalog: catalog1 deleted successfully
{ "error-code": 400, "message": "", "stack-trace": null, "type": "google.rpc.ErrorInfo", "reason": null, "metadata": {} }{ "error-code": 401, "message": "", "stack-trace": null, "type": "google.rpc.ErrorInfo", "reason": null, "metadata": {} }{ "error-code": 404, "message": "", "stack-trace": null, "type": "google.rpc.ErrorInfo", "reason": null, "metadata": {} }{ "error-code": 500, "message": "InternalServerError", "stack-trace": null, "type": "google.rpc.ErrorInfo", "reason": null, "metadata": {} }
Request
Create a Schema
Name of schema, relative to parent catalog.
Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-zA-Z0-9]*$Name of parent catalog.
Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-zA-Z0-9]*$User-provided free-form text description.
Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-zA-Z0-9]*$A map of key-value properties attached to the securable.
curl -X POST -H "accept: application/json" -H "Authorization: ••••••" -H "Content-Type: application/json" -d '{"name": "schema1", "catalog_name": "catalog1","comment": "My new schema","properties": { "locationUri": "s3a://ibm_bucket/schema1.db"}}' "https://ibm-lh-lakehouse-mds-rest-cpd-instance.apps.enginecluster-fipsmds02.cp.fyre.ibm.com/api/2.1/unity-catalog/schemas"
Response
Information about Schema
Name of schema, relative to parent catalog.
Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-zA-Z0-9_ ]*$Name of parent catalog.
Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-zA-Z0-9_ ]*$User-provided free-form text description.
Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-zA-Z0-9_ ]*$A map of key-value properties attached to the securable.
Full name of schema, in form of catalog_name.schema_name.
Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-zA-Z0-9_.]*$Username of current owner of schema.
Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-zA-Z0-9_ ]*$Time at which this schema was created, in epoch milliseconds.
Possible values: 0 ≤ value ≤ 1000000000000000
Username of schema creator.
Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-zA-Z0-9]*$Time at which this schema was last modified, in epoch milliseconds.
Possible values: 0 ≤ value ≤ 1000000000000000
Username of user who last modified schema.
Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-zA-Z0-9]*$Unique identifier for the schema.
Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-zA-Z0-9]*$New name for the schema.
Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-zA-Z0-9]*$
Status Code
The new schema was successfully created.
Bad Request
Unauthorized
Not found
InternalServerError
{ "name": "schema1", "catalog_name": "catalog1", "comment": "My new Schema", "properties": { "locationUri": "s3a://ibm_bucket/schema1.db" }, "full_name": "catalog1.schema1", "created_at": 1747298641, "updated_at": 0, "schema_id": "2" }{ "error-code": 400, "message": "", "stack-trace": null, "type": "google.rpc.ErrorInfo", "reason": null, "metadata": {} }{ "error-code": 401, "message": "", "stack-trace": null, "type": "google.rpc.ErrorInfo", "reason": null, "metadata": {} }{ "error-code": 404, "message": "", "stack-trace": null, "type": "google.rpc.ErrorInfo", "reason": null, "metadata": {} }{ "error-code": 500, "message": "InternalServerError", "stack-trace": null, "type": "google.rpc.ErrorInfo", "reason": null, "metadata": {} }
List schemas
Gets an array of schemas for a catalog. There is no guarantee of a specific ordering of the elements in the array.
GET /schemas
Request
Query Parameters
Parent catalog for schemas of interest.
Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-zA-Z0-9]*$Example:
catalog1Maximum number of schemas to return.
- when set to a value greater than 0, the page length is the minimum of this value and a server configured value;
- when set to 0, the page length is set to a server configured value;
- when set to a value less than 0, an invalid parameter error is returned;
Possible values: 0 ≤ value ≤ 1000000000000000
Opaque pagination token to go to next page based on previous query.
Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-zA-Z0-9]*$
curl -X GET -H "accept: application/json" -H "Authorization: ••••••" -H "Content-Type: application/json" "https://ibm-lh-lakehouse-mds-rest-cpd-instance.apps.enginecluster-fipsmds02.cp.fyre.ibm.com/api/2.1/unity-catalog/schemas?catalog_name=catalog1"
Response
List Schema Response
An array of schema information objects.
Possible values: 0 ≤ number of items ≤ 250
Opaque token to retrieve the next page of results. Absent if there are no more pages. page_token should be set to this value for the next request (for the next page of results).
Possible values: 1 ≤ length ≤ 100000, Value must match regular expression
^[a-zA-Z0-9]*$
Status Code
The schemas list was successfully retrieved.
Bad Request
Unauthorized
Not found
InternalServerError
{ "schemas": [ { "name": "schema1", "catalog_name": "catalog1", "comment": "My new Schema", "properties": { "locationUri": "s3a://ibm_bucket/schema1.db" }, "full_name": "catalog1.schema1", "created_at": 1747298641, "updated_at": 0, "schema_id": "2" } ] }{ "error-code": 400, "message": "", "stack-trace": null, "type": "google.rpc.ErrorInfo", "reason": null, "metadata": {} }{ "error-code": 401, "message": "", "stack-trace": null, "type": "google.rpc.ErrorInfo", "reason": null, "metadata": {} }{ "error-code": 404, "message": "", "stack-trace": null, "type": "google.rpc.ErrorInfo", "reason": null, "metadata": {} }{ "error-code": 500, "message": "InternalServerError", "stack-trace": null, "type": "google.rpc.ErrorInfo", "reason": null, "metadata": {} }
Request
Path Parameters
Full name of the schema.
Possible values: 1 ≤ length ≤ 256, Value must match regular expression
^[a-zA-Z0-9.-_]*$Example:
catalog1.schema1
curl -X GET -H "accept: application/json" -H "Authorization: ••••••" -H "Content-Type: application/json" "https://ibm-lh-lakehouse-mds-rest-cpd-instance.apps.enginecluster-fipsmds02.cp.fyre.ibm.com/api/2.1/unity-catalog/schemas/catalog1.schema1"
Response
Information about Schema
Name of schema, relative to parent catalog.
Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-zA-Z0-9_ ]*$Name of parent catalog.
Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-zA-Z0-9_ ]*$User-provided free-form text description.
Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-zA-Z0-9_ ]*$A map of key-value properties attached to the securable.
Full name of schema, in form of catalog_name.schema_name.
Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-zA-Z0-9_.]*$Username of current owner of schema.
Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-zA-Z0-9_ ]*$Time at which this schema was created, in epoch milliseconds.
Possible values: 0 ≤ value ≤ 1000000000000000
Username of schema creator.
Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-zA-Z0-9]*$Time at which this schema was last modified, in epoch milliseconds.
Possible values: 0 ≤ value ≤ 1000000000000000
Username of user who last modified schema.
Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-zA-Z0-9]*$Unique identifier for the schema.
Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-zA-Z0-9]*$New name for the schema.
Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-zA-Z0-9]*$
Status Code
The schema was successfully retrieved.
Bad Request
Unauthorized
Not found
InternalServerError
{ "name": "schema1", "catalog_name": "catalog1", "comment": "My new Schema", "properties": { "locationUri": "s3a://ibm_bucket/schema1.db" }, "full_name": "catalog1.schema1", "created_at": 1747298641, "updated_at": 0, "schema_id": "2" }{ "error-code": 400, "message": "", "stack-trace": null, "type": "google.rpc.ErrorInfo", "reason": null, "metadata": {} }{ "error-code": 401, "message": "", "stack-trace": null, "type": "google.rpc.ErrorInfo", "reason": null, "metadata": {} }{ "error-code": 404, "message": "", "stack-trace": null, "type": "google.rpc.ErrorInfo", "reason": null, "metadata": {} }{ "error-code": 500, "message": "InternalServerError", "stack-trace": null, "type": "google.rpc.ErrorInfo", "reason": null, "metadata": {} }
Request
Path Parameters
Full name of the schema.
Possible values: 1 ≤ length ≤ 256, Value must match regular expression
^[a-zA-Z0-9.-_]*$Example:
catalog1.schema1
Update Schema
User-provided free-form text description.
Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-zA-Z0-9]*$A map of key-value properties attached to the securable.
New name for the schema.
Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-zA-Z0-9]*$
curl -X PATCH -H "accept: application/json" -H "Authorization: ••••••" -H "Content-Type: application/json" -d "comment": "new comment for schema schema_updated", "properties": { "locationUri": "s3a://ibm_bucket/schema_updated"},"new_name": "schema_updated" "https://ibm-lh-lakehouse-mds-rest-cpd-instance.apps.enginecluster-fipsmds02.cp.fyre.ibm.com/api/2.1/unity-catalog/schemas/catalog1.schema1"
Response
Information about Schema
Name of schema, relative to parent catalog.
Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-zA-Z0-9_ ]*$Name of parent catalog.
Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-zA-Z0-9_ ]*$User-provided free-form text description.
Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-zA-Z0-9_ ]*$A map of key-value properties attached to the securable.
Full name of schema, in form of catalog_name.schema_name.
Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-zA-Z0-9_.]*$Username of current owner of schema.
Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-zA-Z0-9_ ]*$Time at which this schema was created, in epoch milliseconds.
Possible values: 0 ≤ value ≤ 1000000000000000
Username of schema creator.
Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-zA-Z0-9]*$Time at which this schema was last modified, in epoch milliseconds.
Possible values: 0 ≤ value ≤ 1000000000000000
Username of user who last modified schema.
Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-zA-Z0-9]*$Unique identifier for the schema.
Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-zA-Z0-9]*$New name for the schema.
Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-zA-Z0-9]*$
Status Code
The schema was successfully updated.
Bad Request
Unauthorized
Not found
InternalServerError
{ "name": "schema_updated", "catalog_name": "catalog2", "comment": "new comment for schema schema_updated", "properties": { "locationUri": "s3a://ibm_bucket/schema_updated" }, "full_name": "catalog2.schema_updated", "created_at": 1747323154589, "updated_at": 1747323154589, "schema_id": "2" }{ "error-code": 400, "message": "", "stack-trace": null, "type": "google.rpc.ErrorInfo", "reason": null, "metadata": {} }{ "error-code": 401, "message": "", "stack-trace": null, "type": "google.rpc.ErrorInfo", "reason": null, "metadata": {} }{ "error-code": 404, "message": "", "stack-trace": null, "type": "google.rpc.ErrorInfo", "reason": null, "metadata": {} }{ "error-code": 500, "message": "InternalServerError", "stack-trace": null, "type": "google.rpc.ErrorInfo", "reason": null, "metadata": {} }
Request
Path Parameters
Full name of the schema.
Possible values: 1 ≤ length ≤ 256, Value must match regular expression
^[a-zA-Z0-9.-_]*$Example:
catalog1.schema1
Query Parameters
Force deletion even if the catalog is not empty.
curl -X DELETE -H "accept: application/json" -H "Authorization: ••••••" -H "Content-Type: application/json" "https://ibm-lh-lakehouse-mds-rest-cpd-instance.apps.enginecluster-fipsmds02.cp.fyre.ibm.com/api/2.1/unity-catalog/schemas/catalog1.schema1"
Response
Status Code
The schema was successfully deleted.
Bad Request
Unauthorized
Not found
InternalServerError
true{ "error-code": 400, "message": "", "stack-trace": null, "type": "google.rpc.ErrorInfo", "reason": null, "metadata": {} }{ "error-code": 401, "message": "", "stack-trace": null, "type": "google.rpc.ErrorInfo", "reason": null, "metadata": {} }{ "error-code": 404, "message": "", "stack-trace": null, "type": "google.rpc.ErrorInfo", "reason": null, "metadata": {} }{ "error-code": 500, "message": "InternalServerError", "stack-trace": null, "type": "google.rpc.ErrorInfo", "reason": null, "metadata": {} }
Request
Create a table
Name of table, relative to parent schema.
Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-zA-Z0-9]*$Name of parent catalog.
Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-zA-Z0-9]*$Name of parent schema relative to its parent catalog.
Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-zA-Z0-9]*$Table Type
Allowable values: [
MANAGED,EXTERNAL]Data source format
Allowable values: [
CSV,JSON,AVRO,PARQUET,ORC,TEXT,ICEBERG,HIVE,HUDI,DELTA]The array of ColumnInfo definitions of the table's columns.
Possible values: 0 ≤ number of items ≤ 250
Storage root URL for external table
Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-zA-Z0-9]*$User-provided free-form text description.
Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-zA-Z0-9]*$A map of key-value properties attached to the securable.
- properties
Additional properties
Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-zA-Z0-9]*$
curl -X POST -H "accept: application/json" -H "Authorization: ••••••" -H "Content-Type: application/json" -d "{" "name": "table1", "catalog_name": "catalog1", "schema_name": "schema1", "table_type": "EXTERNAL", "data_source_format": "iceberg", "columns": [{ "name": "id", "type_text": "string", "type_json": "string", "type_name": "BOOLEAN", "type_precision": 0, "type_scale": 0, "type_interval_type": "string", "position": 0, "comment": "string", "nullable": true, "partition_index": 0 }], "storage_location": "s3a://mdsbucket/path1/path3/path5/presto-warehouse/ad_hive_schema/my_table_ad", "comment": "a new table", "properties": { "additionalProp1": "string" } }" "https://ibm-lh-lakehouse-mds-rest-cpd-instance.apps.enginecluster-fipsmds02.cp.fyre.ibm.com/api/2.1/unity-catalog/tables"
Response
Table Info
Table Type
Possible values: [
MANAGED,EXTERNAL]Data source format
Possible values: [
CSV,JSON,AVRO,PARQUET,ORC,TEXT,ICEBERG,HIVE,HUDI,DELTA]The array of ColumnInfo definitions of the table's columns.
Possible values: 0 ≤ number of items ≤ 250
Name of table, relative to parent schema.
Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-zA-Z0-9 _]*$Example:
stringName of parent catalog.
Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-zA-Z0-9]*$Example:
stringName of parent schema relative to its parent catalog.
Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-zA-Z0-9 _]*$Example:
stringStorage root URL for table (for MANAGED, EXTERNAL tables)
Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-zA-Z0-9]*://[A-Za-z0-9-]{3,63}(?:.[A-Za-z0-9-]{3,63})*(/[A-Za-z0-9-_/]+)*$User-provided free-form text description.
Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-zA-Z0-9]*$Example:
stringA map of key-value properties attached to the securable.
- properties
Additional properties
Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-zA-Z0-9]*$
Username of current owner of table.
Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-zA-Z0-9]*$Example:
stringTime at which this table was created, in epoch milliseconds.
Possible values: 0 ≤ value ≤ 1000000000000000
Username of table creator.
Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-zA-Z0-9]*$Example:
stringTime at which this table was last modified, in epoch milliseconds.
Possible values: 0 ≤ value ≤ 1000000000000000
Username of user who last modified the table.
Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-zA-Z0-9]*$Example:
stringUnique identifier for the table.
Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-zA-Z0-9]*$Example:
string
Status Code
The new external table was successfully created.
Bad Request
Unauthorized
Not found
InternalServerError
{ "name": "table1", "columns": [ { "name": "id", "position": 0, "comment": "string", "nullable": false, "type_text": "string", "type_json": "string", "type_name": "STRING", "type_precision": 0, "type_scale": 0, "type_interval_type": null, "partition_index": 1 } ], "comment": null, "properties": { "additionalProp1": "string", "data_source_format": "iceberg" }, "catalog_name": "catalog1", "schema_name": "schema1", "table_type": "EXTERNAL", "data_source_format": "ICEBERG", "storage_location": "s3a://mdsbucket/path1/path3/path5/presto-warehouse/ad_hive_schema/my_table_ad", "created_at": 1748523046000, "updated_at": 0, "table_id": "0" }{ "error-code": 400, "message": "", "stack-trace": null, "type": "google.rpc.ErrorInfo", "reason": null, "metadata": {} }{ "error-code": 401, "message": "", "stack-trace": null, "type": "google.rpc.ErrorInfo", "reason": null, "metadata": {} }{ "error-code": 404, "message": "", "stack-trace": null, "type": "google.rpc.ErrorInfo", "reason": null, "metadata": {} }{ "error-code": 500, "message": "InternalServerError", "stack-trace": null, "type": "google.rpc.ErrorInfo", "reason": null, "metadata": {} }
List tables
Gets the list of all available tables under the parent catalog and schema. There is no guarantee of a specific ordering of the elements in the array.
GET /tables
Request
Query Parameters
Name of parent catalog for tables of interest.
Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-zA-Z0-9]*$Parent schema of tables.
Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-zA-Z0-9]*$Maximum number of tables to return.
- when set to a value greater than 0, the page length is the minimum of this value and a server configured value;
- when set to 0, the page length is set to a server configured value;
- when set to a value less than 0, an invalid parameter error is returned;
Possible values: 0 ≤ value ≤ 1000000000000000
Opaque token to send for the next page of results (pagination).
Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-zA-Z0-9]*$
curl -X GET -H "accept: application/json" -H "Authorization: ••••••" -H "Content-Type: application/json" "https://ibm-lh-lakehouse-mds-rest-cpd-instance.apps.enginecluster-fipsmds02.cp.fyre.ibm.com/api/2.1/unity-catalog/tables?catalog_name=catalog1&schema_name=schema1"
Response
List of Tables
An array of table information objects.
Possible values: 0 ≤ number of items ≤ 10000
Opaque token to retrieve the next page of results. Absent if there are no more pages. page_token should be set to this value for the next request (for the next page of results).
Possible values: 1 ≤ length ≤ 100000, Value must match regular expression
^[a-zA-Z0-9]*$
Status Code
The tables list was successfully retrieved.
Bad Request
Unauthorized
Not found
InternalServerError
{ "tables": [ { "name": "table1", "columns": [ { "name": "id", "position": 0, "comment": null, "nullable": false, "type_text": "string", "type_json": "string", "type_name": "STRING", "type_precision": 0, "type_scale": 0, "type_interval_type": null, "partition_index": 1 } ], "comment": null, "properties": { "additionalProp1": "string", "EXTERNAL": "TRUE", "write.parquet.compression-codec": "zstd", "transient_lastDdlTime": "1748523116", "current-schema": "{\"type\":\"struct\",\"schema-id\":0,\"fields\":[{\"id\":1,\"name\":\"id\",\"required\":false,\"type\":\"string\"}]}", "metadata_location": "s3a://mdsbucket/path1/path3/path5/presto-warehouse/ad_hive_schema/my_table_ad/metadata/00000-80f513a8-c5ad-4fc7-9e94-fe6582eba710.metadata.json", "snapshot-count": "0", "data_source_format": "iceberg", "uuid": "6091a98b-4391-4489-9f19-1f7de8dcd3fa", "table_type": "ICEBERG" }, "catalog_name": "catalog1", "schema_name": "schema1", "table_type": "EXTERNAL", "data_source_format": "ICEBERG", "storage_location": "s3a://mdsbucket/path1/path3/path5/presto-warehouse/ad_hive_schema/my_table_ad", "created_at": 1748523067000, "updated_at": 0, "table_id": "21" } ] }{ "error-code": 400, "message": "", "stack-trace": null, "type": "google.rpc.ErrorInfo", "reason": null, "metadata": {} }{ "error-code": 401, "message": "", "stack-trace": null, "type": "google.rpc.ErrorInfo", "reason": null, "metadata": {} }{ "error-code": 404, "message": "", "stack-trace": null, "type": "google.rpc.ErrorInfo", "reason": null, "metadata": {} }{ "error-code": 500, "message": "InternalServerError", "stack-trace": null, "type": "google.rpc.ErrorInfo", "reason": null, "metadata": {} }
Request
Path Parameters
Full name of the table.
Possible values: 1 ≤ length ≤ 100000, Value must match regular expression
^[a-zA-Z0-9]*$
curl -X GET -H "accept: application/json" -H "Authorization: ••••••" -H "Content-Type: application/json" "https://ibm-lh-lakehouse-mds-rest-cpd-instance.apps.enginecluster-fipsmds02.cp.fyre.ibm.com/api/2.1/unity-catalog/tables/catalog1.schema1.table1"
Response
Table Info
Table Type
Possible values: [
MANAGED,EXTERNAL]Data source format
Possible values: [
CSV,JSON,AVRO,PARQUET,ORC,TEXT,ICEBERG,HIVE,HUDI,DELTA]The array of ColumnInfo definitions of the table's columns.
Possible values: 0 ≤ number of items ≤ 250
Name of table, relative to parent schema.
Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-zA-Z0-9 _]*$Example:
stringName of parent catalog.
Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-zA-Z0-9]*$Example:
stringName of parent schema relative to its parent catalog.
Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-zA-Z0-9 _]*$Example:
stringStorage root URL for table (for MANAGED, EXTERNAL tables)
Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-zA-Z0-9]*://[A-Za-z0-9-]{3,63}(?:.[A-Za-z0-9-]{3,63})*(/[A-Za-z0-9-_/]+)*$User-provided free-form text description.
Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-zA-Z0-9]*$Example:
stringA map of key-value properties attached to the securable.
- properties
Additional properties
Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-zA-Z0-9]*$
Username of current owner of table.
Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-zA-Z0-9]*$Example:
stringTime at which this table was created, in epoch milliseconds.
Possible values: 0 ≤ value ≤ 1000000000000000
Username of table creator.
Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-zA-Z0-9]*$Example:
stringTime at which this table was last modified, in epoch milliseconds.
Possible values: 0 ≤ value ≤ 1000000000000000
Username of user who last modified the table.
Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-zA-Z0-9]*$Example:
stringUnique identifier for the table.
Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-zA-Z0-9]*$Example:
string
Status Code
The table was successfully retrieved.
Bad Request
Unauthorized
Not found
InternalServerError
{ "name": "table1", "columns": [ { "name": "id", "position": 0, "comment": "", "nullable": false, "type_text": "string", "type_json": "string", "type_name": "STRING", "type_precision": 0, "type_scale": 0, "type_interval_type": null, "partition_index": 1 } ], "comment": null, "properties": { "EXTERNAL": "TRUE", "additionalProp1": "string", "write.parquet.compression-codec": "zstd", "metadata_location": "s3a://mdsbucket/path1/path3/path5/presto-warehouse/ad_hive_schema/my_table_ad/metadata/00000-80f513a8-c5ad-4fc7-9e94-fe6582eba710.metadata.json", "current-schema": "{\"type\":\"struct\",\"schema-id\":0,\"fields\":[{\"id\":1,\"name\":\"id\",\"required\":false,\"type\":\"string\"}]}", "transient_lastDdlTime": "1748523116", "data_source_format": "iceberg", "snapshot-count": "0", "uuid": "6091a98b-4391-4489-9f19-1f7de8dcd3fa", "table_type": "ICEBERG" }, "catalog_name": "catalog1", "schema_name": "schema1", "table_type": "EXTERNAL", "data_source_format": "ICEBERG", "storage_location": "s3a://mdsbucket/path1/path3/path5/presto-warehouse/ad_hive_schema/my_table_ad", "created_at": 1748523067000, "updated_at": 0, "table_id": "21" }{ "error-code": 400, "message": "", "stack-trace": null, "type": "google.rpc.ErrorInfo", "reason": null, "metadata": {} }{ "error-code": 401, "message": "", "stack-trace": null, "type": "google.rpc.ErrorInfo", "reason": null, "metadata": {} }{ "error-code": 404, "message": "", "stack-trace": null, "type": "google.rpc.ErrorInfo", "reason": null, "metadata": {} }{ "error-code": 500, "message": "InternalServerError", "stack-trace": null, "type": "google.rpc.ErrorInfo", "reason": null, "metadata": {} }
Delete a table
Deletes a table from the specified parent catalog and schema.
DELETE /tables/{full_name}Request
Path Parameters
Full name of the table.
Possible values: 1 ≤ length ≤ 100000, Value must match regular expression
^[a-zA-Z0-9]*$
curl -X DELETE -H "accept: application/json" -H "Authorization: ••••••" -H "Content-Type: application/json" "https://ibm-lh-lakehouse-mds-rest-cpd-instance.apps.enginecluster-fipsmds02.cp.fyre.ibm.com/api/2.1/unity-catalog/tables/catalog1.schema1.table1"
Response
Status Code
The table was successfully deleted.
Bad Request
Unauthorized
Not found
InternalServerError
true{ "error-code": 400, "message": "Schema schema1 not found", "stack-trace": null, "type": "google.rpc.ErrorInfo", "reason": null, "metadata": {} }{ "error-code": 401, "message": "", "stack-trace": null, "type": "google.rpc.ErrorInfo", "reason": null, "metadata": {} }{ "error-code": 404, "message": "", "stack-trace": null, "type": "google.rpc.ErrorInfo", "reason": null, "metadata": {} }{ "error-code": 500, "message": "An unexpected error occurred in Unity Catalog.", "stack-trace": null, "type": "google.rpc.ErrorInfo", "reason": null, "metadata": {} }
Get a temporary table credentials
Generates Temporary Table credentials
POST /temporary-table-credentials
Request
Request for Temporary Table credentials
{
"operation": "READ",
"table_id": "10"
}Table id
Possible values: 1 ≤ length ≤ 1000000, Value must match regular expression
^[a-zA-Z0-9 ]*$Operation to be performed
Allowable values: [
UNKNOWN_TABLE_OPERATION,READ,READ_WRITE]
curl -X POST -H "accept: application/json" -H "Authorization: ••••••" -H "Content-Type: application/json" -d '{"table_id":"10","operation":"UNKNOWN_TABLE_OPERATION"}' "https://ibm-lh-lakehouse-mds-rest-cpd-instance.apps.enginecluster-fipsmds02.cp.fyre.ibm.com/api/2.1/unity-catalog/temporary-table-credentials"
Response
Response for credential APIs
Possible values: 1 ≤ length ≤ 1000000, Value must match regular expression
^[a-zA-Z0-9 ]*$Possible values: 1 ≤ length ≤ 1000000, Value must match regular expression
^[a-zA-Z0-9 ]*$Possible values: 1 ≤ length ≤ 1000000, Value must match regular expression
^[a-zA-Z0-9 ]*$Possible values: 0 ≤ value ≤ 1000000000000000
Status Code
OK
Bad Request
Unauthorized
Not found
InternalServerError
{ "aws_temp_credentials": { "access_key_id": "dummy access key id", "secret_access_key": "dummy secret access key", "session_token": "dummy session token" }, "azure_user_delegation_sas": null, "gcp_oauth_token": null, "expiration_time": null }{ "error-code": 400, "message": "", "stack-trace": null, "type": "google.rpc.ErrorInfo", "reason": null, "metadata": {} }{ "error-code": 401, "message": "", "stack-trace": null, "type": "google.rpc.ErrorInfo", "reason": null, "metadata": {} }{ "error-code": 404, "message": "", "stack-trace": null, "type": "google.rpc.ErrorInfo", "reason": null, "metadata": {} }{ "error-code": 500, "message": "InternalServerError", "stack-trace": null, "type": "google.rpc.ErrorInfo", "reason": null, "metadata": {} }
Get a temporary path credentials
Generated temporary path credentials
POST /temporary-path-credentials
Request
Get a temporary Path credential
{
"url": "abfss://pyspark@sparkadlsiae.dfs.core.windows.net",
"operation": "PATH_CREATE_TABLE"
}url
Possible values: 1 ≤ length ≤ 128, Value must match regular expression
^[a-zA-Z0-9:@./-]+$Operation
Allowable values: [
UNKNOWN_PATH_OPERATION,PATH_READ,PATH_READ_WRITE,PATH_CREATE_TABLE]
curl -X POST -H "accept: application/json" -H "Authorization: ••••••" -H "Content-Type: application/json" -d '{"url":"abfss://pyspark@sparkadlsiae.blob.core.windows.net/","operation":"PATH_CREATE_TABLE"}' "https://ibm-lh-lakehouse-mds-rest-cpd-instance.apps.enginecluster-fipsmds02.cp.fyre.ibm.com/api/2.1/unity-catalog/temporary-path-credentials"
Response
Response for credential APIs
Possible values: 1 ≤ length ≤ 1000000, Value must match regular expression
^[a-zA-Z0-9 ]*$Possible values: 1 ≤ length ≤ 1000000, Value must match regular expression
^[a-zA-Z0-9 ]*$Possible values: 1 ≤ length ≤ 1000000, Value must match regular expression
^[a-zA-Z0-9 ]*$Possible values: 0 ≤ value ≤ 1000000000000000
Status Code
OK
Bad Request
Unauthorized
Not found
InternalServerError
{ "aws_temp_credentials": null, "azure_user_delegation_sas": { "sas_token": "sv=2025-01-05&st=2025-05-29T10%3A57%3A54Z&se=2025-05-29T11%3A57%3A54Z&skoid=bc71c096-2f7d-4b2c-afcc-721e0b3446b9&sktid=0d909434-4142-4034-8b85-691ead3660b6&skt=2025-05-29T10%3A57%3A54Z&ske=2025-05-29T11%3A57%3A54Z&sks=b&skv=2025-01-05&sr=c&sp=rwdl&sig=nsXKg5MbflTGnCeOEA3LzXZhUwmCF0CTML7qTMgLb9g%3D" }, "gcp_oauth_token": null, "expiration_time": 1748519874234 }{ "error-code": 404, "message": "", "stack-trace": null, "type": "google.rpc.ErrorInfo", "reason": null, "metadata": {} }{ "error-code": 500, "message": "InternalServerError", "stack-trace": null, "type": "google.rpc.ErrorInfo", "reason": null, "metadata": {} }