# (NEW!) Create Metadata Table

Create a new metadata table in a single call.

Defaults:
- isSmartTable defaults to false.

Business Rules:
- tableFields must contain between 1 and 12 effective columns — a plain or controlled-vocabulary field counts as 1, a cascade field counts as its number of levels. Example: a table with 9 plain fields can add one more cascade only if that cascade has 3 or fewer levels.
- Each tableFields[].fieldId must reference an existing attribute or cascade (never another table); no two entries may reference the same fieldId.
- isSingleRow and isSmartTable are mutually exclusive and permanently fixed once set.
- isSmartTable is subject to a 25-per-customer smart-table cap, enforced at creation time.
- A duplicate name/searchField is rejected with 409.

The user submitting the request must have the Metadata Template Management admin privilege.

Endpoint: POST /metadata/tables
Version: 1.5
Security: ApiKeyAuth, BasicAuth

## Header parameters:

  - `Authorization` (string, required)
    Provided by Authentication Token creation operation.

  - `Content-Type` (string, required)
    Enum: "application/json"

## Request fields (application/json):

  - `name` (string, required)
    Display name for the new table. Maximum 32 characters.
    Example: "Store Locations Table"

  - `isSingleRow` (boolean, required)
    Whether the table is single-row. Permanent once set.

  - `isSmartTable` (boolean)
    Whether the table is a smart table. Defaults to false. Permanent once set; mutually exclusive with isSingleRow: true. Subject to a 25-per-customer smart-table cap, enforced at creation time.

  - `tableFields` (array, required)
    Columns for the table. Between 1 and 12 effective columns — a plain or controlled-vocabulary field counts as 1, a cascade field counts as its number of levels. Each fieldId must reference an existing attribute or cascade (never another table); no two entries may reference the same fieldId.

  - `tableFields.fieldOrder` (integer, required)
    Display order.
    Example: 1

  - `tableFields.fieldId` (string, required)
    Id of the existing attribute or cascade backing this column.
    Example: "d3f8a1c2-6b4e-4a17-9c3f-2e7b5d0a8f61"

## Response 201 fields (application/json):

  - `id` (string)
    Unique ID of the table.
    Example: "e6a91f4c-8b2d-4a17-9c6e-3f5a8d1b7c92"

  - `name` (string)
    Display name of the table.
    Example: "Store Locations Table"

  - `searchField` (string)
    System-generated slug. Permanent once created.
    Example: "store_locations_table"

  - `isSingleRow` (boolean)
    Fixed at creation.

  - `isSmartTable` (boolean)
    Fixed at creation. Remains false while a standard-to-smart conversion is pending (see convertTo).

  - `convertTo` (string,null)
    Set to smart while a standard-to-smart conversion is pending "Apply Changes"; null otherwise.
    Enum: "smart"

  - `featured` (boolean,null)
    System-assigned. null if never set. Blocks deletion when true.

  - `tableFields` (array)
    Ordered columns. Stays flat even for a cascade-backed column — no nested expansion of the cascade's own levels here.

  - `tableFields.fieldOrder` (integer)
    Display order.
    Example: 1

  - `tableFields.fieldId` (string)
    Id of the attribute or cascade backing this column.
    Example: "d3f8a1c2-6b4e-4a17-9c3f-2e7b5d0a8f61"

  - `tableFields.fieldName` (string)
    Denormalized display name.
    Example: "Store Name"

  - `tableFields.fieldType` (string)
    The column's underlying type, so the UI can render the right control/icon without a second lookup.
    Enum: "textbox", "textarea", "date", "dropdown", "cascade"

  - `createdBy` (string)
    User-profile id of the table's creator.
    Example: "8f2a5c91-4e6d-4b83-9a17-6c0d3e8b2f45"

  - `createdEpoch` (integer)
    Unix timestamp (ms) of creation.
    Example: 1772704800000

  - `createdDate` (string)
    ISO 8601 creation date.
    Example: "2026-03-05T10:00:00Z"

  - `lastUpdatedBy` (string)
    User-profile id of the last user to update the table.
    Example: "8f2a5c91-4e6d-4b83-9a17-6c0d3e8b2f45"

  - `lastUpdatedEpoch` (integer)
    Unix timestamp (ms) of the last update.
    Example: 1773325200000

  - `lastUpdatedDate` (string)
    ISO 8601 last-updated date.
    Example: "2026-03-12T14:20:00Z"

  - `usedIn` (object)
    Where the table is currently referenced. Does not include an attributes category — attributes never reference a table; a table contains attributes as its columns, never the reverse.

  - `usedIn.metadataGroups` (array)
    Groups that reference this table.

  - `usedIn.metadataGroups.id` (string)
    Example: "52ce0235-02cc-46f6-8bdb-05238c76bf83"

  - `usedIn.metadataGroups.name` (string)
    Example: "Product Information"

  - `usedIn.metadataTemplates` (array)
    Templates that reference this table.

## Response 400 fields (application/json):

  - `status` (string)
    Example: "error"

  - `message` (string)

## Response 401 fields (application/json):

  - `status` (string)
    Example: "error"

  - `message` (string)

## Response 403 fields (application/json):

  - `status` (string)
    Example: "error"

  - `message` (string)

## Response 409 fields (application/json):

  - `status` (string)
    Example: "error"

  - `message` (string)