Hello @camilo_s , thanks for sharing the doc link and the details you observed in the UI network calls.
Short answer
- There isnโt a documented, stable, public REST endpoint specifically for โtags on UC securablesโ today. You should use SQL DDL to manage tags and (if you need REST) call the SQL Statement Execution API to run those SQL statements programmatically on a SQL Warehouse.
- The endpoint you saw in the browser (
/ajax-api/2.1/unity-catalog/securable-tags/...) is an internal UI path and is deliberately not exposed publicly at this time.
What is supported today - Use SQL to add or remove tags:
- Databricks Runtime 16.1+:
SET TAG / UNSET TAG on catalogs, schemas, tables, columns, views, volumes, models, and model versions.
- Databricks Runtime 13.3+:
ALTER <object> ... SET TAGS (...) / UNSET TAGS for objects and columns.
-
Run those SQL statements via REST using the Databricks SQL Statement Execution API (POST /api/2.0/sql/statements) against a SQL Warehouse, which lets you programmatically set tags without using undocumented endpoints.
-
Required privileges to tag: You need APPLY TAG on the object, plus USE CATALOG and USE SCHEMA on the parents; for governed tags, you also need ASSIGN on the tag policy.
-
Models (registered in UC) can also be tagged via the MLflow Client API (for model and model version tags).
About the internal endpoint you found
- The UI does use an internal, UI-proxy path to read/update securable tags:
/ajax-api/2.1/unity-catalog/securable-tags/{SECURABLE_TYPE}/{full_name}. This path is intentionally not publicly documented because the tagging API surface is evolving alongside governed tags and account-level policies, and could change in a breaking way.
- You can see it in HAR traces from Catalog Explorer (for example, schema and catalog tag reads/writes), but itโs not for external client consumption.
Roadmap and plans
- Databricks has introduced governed tags and tag policies (account-level constraints with allowed values and assignment permissions). These are in Public Preview and are being expanded with ABAC policy enforcement and broader ecosystem support.
- There is private-preview documentation that includes โTag Assignmentsโ APIs (for securables and columns), but these are subject to change and not generally available; weโre deliberately avoiding publishing unstable endpoints until the surface is finalized.
- Audit logs already record governed-tag assignment/list/update actions, which reflects ongoing productization of tag governance, but does not imply public GA of specific endpoints yet.
Databricks does not publicly commit timelines for enabling new REST surfaces; the recommended approach today is to use SQL DDL for tags and drive it through the Statement Execution API where you need REST automation.
Example:
Tag via REST today (using SQL Statement Execution API) bash
# Example: set a tag on a table via SQL Statement Execution API
curl --request POST \
https://<workspace-host>/api/2.0/sql/statements \
--header "Authorization: Bearer <token>" \
--header "Content-Type: application/json" \
--data '{
"warehouse_id": "<SQL_WAREHOUSE_ID>",
"catalog": "main",
"schema": "default",
"statement": "SET TAG ON TABLE main.default.my_table `cost_center` = `hr`"
}'
- Ensure the caller has APPLY TAG on the object (and USE CATALOG / USE SCHEMA), and ASSIGN if the tag is governed.
Terraform
- Your observation is accurate: the current Databricks Terraform provider doesnโt expose a generic โtagsโ attribute for UC securables (e.g., schema) like some cloud providers do; this gap has been raised by users in provider issues, often suggesting internal UI paths exist but arenโt public APIs.
- In practice, teams handle tagging in Terraform by issuing SQL (e.g., via databricks_sql or external orchestration calling the Statement Execution API) rather than relying on an undeclared tags attribute.
Summary
- Use SQL tag DDL and automate via the SQL Statement Execution API for REST-based workflows today.
- The internal
securable-tags endpoint exists for the UI but is not public/documented by design (to avoid future breaking changes while governed tags mature).
- Governed tags and ABAC are moving forward; public, stable tag-management APIs may evolve as part of that work, but thereโs no public ETA to share at this time.
Hope this helps, Louis.
