---
title: "Create or update table metadata"
method: POST
path: "/v2/storage/tables/{id}/metadata"
tags: ["Metadata"]
---

# Create or update table metadata

`POST /v2/storage/tables/{id}/metadata`

## Request

- Base URL: `https://connection.keboola.com`
- URL: `https://connection.keboola.com/v2/storage/tables/{id}/metadata`
- Auth: one of:
  - API key in header `X-StorageApi-Token`
  - API key in header `X-KBC-ManageApiToken`
  - HTTP bearer
- TypeScript: <https://skmtc.dev/keboola/apis/keboola-storage-api/docs/v2/storage/tables/:id/metadata/post.ts> (a function with typed inputs; its response is checked against the schema)

Sets multiple metadata for table and columns with one call. If the given key and provider combination already exist
for the table, the data will be updated with the new value and timestamp. All metadata associated
with the table and columns are returned to the response.

At least one of the `metadata` or `columnsMetadata` object is required. Using columnName as index for `columnsMetadata` is deprecated and not recommended, rather index it by int. Please add columnName to metadata object as described in example.

When the request is not sent as JSON (`application/x-www-form-urlencoded`, deprecated), only the table-level metadata list is returned.

## Path parameters

- `id` string, required

## Request body

- CreateTableMetadataRequest: At least one of `metadata` or `columnsMetadata` is required.
  - `provider` string, required: Id of the creating component
  - `metadata` object[]: Array of table metadata objects
    - `key` string, required: Metadata key (`a-zA-Z0-9_.-`, max 255 chars)
    - `value` string, nullable, required: Metadata value
  - `columnsMetadata` object: Object of column metadata grouped by column, indexed by int (indexing by columnName is deprecated). Each metadata object should carry `columnName`.

## Response `201`

All metadata associated with the table and its columns.

- union
  - TableCreateOrUpdateMetadataResponse
    - `metadata` MetadataItemResponse[], required: Table-level metadata records.
      - `id` string, required: Metadata record identifier
      - `key` string, required: Metadata key
      - `value` string, nullable, required: Metadata value
      - `provider` string, required: Id of the component that created the metadata
      - `timestamp` string, required: When the metadata was created or last updated, ISO 8601 with a `+hhmm` offset
    - `columnsMetadata` object, required: Column metadata keyed by column name.
  - MetadataItemResponse[]: Table-level metadata records only; returned when the request is not sent as JSON.
    - `id` string, required: Metadata record identifier
    - `key` string, required: Metadata key
    - `value` string, nullable, required: Metadata value
    - `provider` string, required: Id of the component that created the metadata
    - `timestamp` string, required: When the metadata was created or last updated, ISO 8601 with a `+hhmm` offset

## Other responses

- `400`: Returned when the metadata payload is invalid (`storage.metadata.invalidParameter`).
- `403`: Returned when the token has no write access to the bucket or the provider is protected (`storage.metadata.invalidProvider`).
- `404`: Returned when the table (`storage.tables.notFound`), column (`storage.tables.columnNotFound`) or bucket (`storage.buckets.notFound`) is not found.

---

[API](https://skmtc.dev/keboola/apis/keboola-storage-api.md) - [All operations](https://skmtc.dev/keboola/apis/keboola-storage-api/llms.txt) - [OpenAPI document](https://skmtc.dev/keboola/apis/keboola-storage-api/revisions/34b5ceac0317?raw)