---
title: Creating, Updating, and Deleting a Reference Table with the API
description: >-
  Complete walkthrough for creating, updating, and deleting a Reference Table
  backed by a local CSV file using the Datadog API.
breadcrumbs: >-
  Docs > Reference Tables > Reference Tables Guides > Creating, Updating, and
  Deleting a Reference Table with the API
---

> For the complete documentation index, see [llms.txt](https://docs.datadoghq.com/llms.txt).

# Creating, Updating, and Deleting a Reference Table with the API

This guide shows the complete workflow for managing a Reference Table backed by a local CSV file with the [Reference Tables API](https://docs.datadoghq.com/api/latest/reference-tables.md). It creates an upload, pushes the CSV data to the returned URLs, creates the table, patches it with new data, and deletes it.

Replace `<DATADOG_API_KEY>` and `<DATADOG_APP_KEY>` with your Datadog API and application keys.

1. Create a reference table upload. Provide the CSV `headers`, the number of parts you plan to upload in `part_count`, and the maximum size of each part in bytes in `part_size`.

   ```shell
   curl -X POST "https://api.<YOUR_DATADOG_SITE>/api/v2/reference-tables/uploads" \
   -H "Content-Type: application/json" \
   -H "DD-API-KEY: <DATADOG_API_KEY>" \
   -H "DD-APPLICATION-KEY: <DATADOG_APP_KEY>" \
   -d '{
     "data": {
       "type": "upload",
       "attributes": {
         "table_name": "my_products_table",
         "headers": ["product_id", "product_name", "price"],
         "part_count": 1,
         "part_size": 10000000
       }
     }
   }'
   ```

The response contains an upload `id` and a `part_urls` array with one URL for each part:

   ```json
   {
     "data": {
       "id": "00000000-0000-0000-0000-000000000000",
       "type": "upload",
       "attributes": {
         "part_urls": ["https://example.com/upload-part-1"]
       }
     }
   }
   ```

1. Upload the CSV data (not the file itself) to each part URL with a `PUT` request. For example, given a `products.csv` file with the following content:

**Note**: If your data spans multiple parts, split the CSV rows evenly and send a separate `PUT` request for each chunk to its corresponding URL in `part_urls`.

   ```csv
   product_id,product_name,price
   1,Widget,9.99
   2,Gadget,19.99
   ```

   ```shell
   curl -X PUT "https://example.com/upload-part-1" \
   -H "Content-Type: text/csv" \
   --data-binary @products.csv
   ```

1. Create the Reference Table, referencing the upload `id` from step 1 in `file_metadata.upload_id`.

   ```shell
   curl -X POST "https://api.<YOUR_DATADOG_SITE>/api/v2/reference-tables/tables" \
   -H "Content-Type: application/json" \
   -H "DD-API-KEY: <DATADOG_API_KEY>" \
   -H "DD-APPLICATION-KEY: <DATADOG_APP_KEY>" \
   -d '{
     "data": {
       "type": "reference_table",
       "attributes": {
         "table_name": "my_products_table",
         "description": "Product catalog uploaded via local file",
         "source": "LOCAL_FILE",
         "file_metadata": {
           "upload_id": "00000000-0000-0000-0000-000000000000"
         },
         "schema": {
           "fields": [
             {"name": "product_id", "type": "STRING"},
             {"name": "product_name", "type": "STRING"},
             {"name": "price", "type": "STRING"}
           ],
           "primary_keys": ["product_id"]
         },
         "tags": ["team:ecommerce"]
       }
     }
   }'
   ```

The response contains the new table's `id`, which you use in the following steps.

1. To update the table's data, repeat steps 1 and 2 to upload a new CSV file, then call the [Update Reference Table endpoint](https://docs.datadoghq.com/api/latest/reference-tables.md#update-reference-table) with the new `upload_id`.

**Note**: The upserted CSV replaces matching rows, adds new rows, and removes rows no longer present in the file.

   ```shell
   curl -X PATCH "https://api.<YOUR_DATADOG_SITE>/api/v2/reference-tables/tables/<TABLE_ID>" \
   -H "Content-Type: application/json" \
   -H "DD-API-KEY: <DATADOG_API_KEY>" \
   -H "DD-APPLICATION-KEY: <DATADOG_APP_KEY>" \
   -d '{
     "data": {
       "type": "reference_table",
       "attributes": {
         "file_metadata": {
           "upload_id": "11111111-1111-1111-1111-111111111111"
         },
         "schema": {
           "fields": [
             {"name": "product_id", "type": "STRING"},
             {"name": "product_name", "type": "STRING"},
             {"name": "price", "type": "STRING"}
           ],
           "primary_keys": ["product_id"]
         }
       }
     }
   }'
   ```

1. To delete the table, call the [Delete Reference Table endpoint](https://docs.datadoghq.com/api/latest/reference-tables.md#delete-table) with the table's `id`.

   ```shell
   curl -X DELETE "https://api.<YOUR_DATADOG_SITE>/api/v2/reference-tables/tables/<TABLE_ID>" \
   -H "DD-API-KEY: <DATADOG_API_KEY>" \
   -H "DD-APPLICATION-KEY: <DATADOG_APP_KEY>"
   ```