Metadata Import API

Bulk import and update metadata for tables, views, and datamaps. Supports updating descriptions, tags, domains, and field-level metadata in a single request.

---

Endpoint

POST https://api.{env}.promethium.ai/metadata/import

---

Headers

Header Name	Value	Required	Description
Content-Type	application/json	✅	Request body format
idtoken	<authentication_id_token>	✅	JWT token obtained via login

---

Request Body

{
  "metadata_objects": [
    {
      "type": "TABLE|VIEW|DATAMAP",
      "id": "string",
      "display_name": "string",
      "description": "string",
      "tags": ["string"],
      "add_tags": ["string"],
      "remove_tags": ["string"],
      "domains": ["string"],
      "add_domains": ["string"],
      "remove_domains": ["string"],
      "fields": [
        {
          "name": "string",
          "description": "string",
          "tags": ["string"],
          "add_tags": ["string"],
          "remove_tags": ["string"]
        }
      ]
    }
  ]
}

Fields

Field	Type	Required	Description
metadata_objects	array	✅	List of objects to update metadata for
type	enum	✅	Object type: TABLE, VIEW, or DATAMAP
id	string	✅	Datamap ID for DATAMAP, FQN for TABLE/VIEW (format: catalog.schema.table_name)
display_name	string	❌	Display name (only for datamaps, cannot be null/empty if provided)
description	string	❌	Object description (null/empty removes value)
tags	string[]	❌	Tags to replace all existing tags (mutually exclusive with add/remove)
add_tags	string[]	❌	Tags to add to existing tags
remove_tags	string[]	❌	Tags to remove from existing tags
domains	string[]	❌	Domain IDs to replace all existing domains (mutually exclusive with add/remove)
add_domains	string[]	❌	Domain IDs to add to existing domains
remove_domains	string[]	❌	Domain IDs to remove from existing domains
fields	array	❌	Field-level metadata (for all entity types)

Field-Level Metadata

Field	Type	Required	Description
fields.name	string	✅	Field/column name
fields.description	string	❌	Field description (null/empty removes value)
fields.tags	string[]	❌	Tags to replace all existing field tags
fields.add_tags	string[]	❌	Tags to add to existing field tags
fields.remove_tags	string[]	❌	Tags to remove from existing field tags

---

Response

Success (200 OK)

{
  "metadata_results": [
    {
      "id": "string",
      "type": "TABLE|VIEW|DATAMAP",
      "fact_id": "string",
      "success": true,
      "fields_processed": true,
      "error_message": null
    }
  ],
  "success_count": 3,
  "failure_count": 0,
  "total_count": 3
}

Field	Type	Description
metadata_results	array	Results for each processed object
metadata_results[].id	string	Object identifier
metadata_results[].type	string	Object type
metadata_results[].fact_id	string	Internal fact ID
metadata_results[].success	boolean	Whether the update succeeded
metadata_results[].fields_processed	boolean	Whether field metadata was processed
metadata_results[].error_message	string	Error message if failed
success_count	integer	Number of successful updates
failure_count	integer	Number of failed updates
total_count	integer	Total objects processed

Error Response

{
  "error": "string",
  "message": "string"
}

HTTP Code	Description	Common Causes
400	Bad Request	Invalid request format, validation errors
401	Unauthorized	Missing or invalid ID token
403	Forbidden	Insufficient permissions
404	Not Found	Object not found by ID/FQN
500	Internal Server Error	System error during processing

---

Validation Rules

Request Validation

• metadata_objects array cannot be empty
• Each object must have valid type and id
• Field names must be unique within each object
• Field name is required when fields array is provided

Business Logic Validation

• Objects must exist in the system (no creation of new objects)
• User must have appropriate permissions for the object type
• For datamaps: must exist with the provided ID
• For tables/views: must exist with the provided FQN in catalog.schema.table_name format
• display_name for datamaps cannot be null or empty when provided

---

Example: curl

Update Table with Field Metadata

curl -X POST https://api.prod.promethium.ai/metadata/import \
  -H "Content-Type: application/json" \
  -H "idtoken: YOUR_ID_TOKEN_HERE" \
  -d '{
    "metadata_objects": [
      {
        "type": "TABLE",
        "id": "sales.public.orders",
        "description": "Customer order transactions with payment details",
        "tags": ["sales", "transactions", "customer_data"],
        "fields": [
          {
            "name": "order_id",
            "description": "Unique order identifier",
            "tags": ["primary_key", "identifier"]
          },
          {
            "name": "customer_email",
            "description": "Customer email address",
            "add_tags": ["pii", "contact"],
            "remove_tags": ["public"]
          }
        ]
      }
    ]
  }'

Update Multiple Object Types

curl -X POST https://api.prod.promethium.ai/metadata/import \
  -H "Content-Type: application/json" \
  -H "idtoken: YOUR_ID_TOKEN_HERE" \
  -d '{
    "metadata_objects": [
      {
        "type": "TABLE",
        "id": "sales.public.orders",
        "description": "Customer order transactions",
        "tags": ["sales", "transactions"]
      },
      {
        "type": "VIEW",
        "id": "analytics.reporting.daily_sales",
        "description": "Daily aggregated sales metrics",
        "add_tags": ["reporting", "daily"],
        "remove_tags": ["raw_data"]
      },
      {
        "type": "DATAMAP",
        "id": "dm_customer_360",
        "display_name": "Customer 360 View",
        "description": "Unified customer profile datamap",
        "add_domains": ["customer_domain", "marketing_domain"]
      }
    ]
  }'

Add and Remove Tags Incrementally

curl -X POST https://api.prod.promethium.ai/metadata/import \
  -H "Content-Type: application/json" \
  -H "idtoken: YOUR_ID_TOKEN_HERE" \
  -d '{
    "metadata_objects": [
      {
        "type": "VIEW",
        "id": "analytics.reporting.daily_sales",
        "add_tags": ["reporting", "daily"],
        "remove_tags": ["raw_data"],
        "fields": [
          {
            "name": "sale_date",
            "description": "Date of sales aggregation",
            "tags": ["temporal", "partition_key"]
          },
          {
            "name": "total_revenue",
            "add_tags": ["kpi", "financial"]
          }
        ]
      }
    ]
  }'