> ## Documentation Index
> Fetch the complete documentation index at: https://docs-docflow.textin.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Tables Management

> Manage table configurations under file categories

<Tip>
  Tables are configurations in file categories used to extract structured tabular data. Each table can contain multiple fields to define the columns of the table. This guide introduces how to manage tables under file categories via API.
</Tip>

## List Tables

Get all tables under a specified file category:

<CodeGroup>
  ```bash curl icon=terminal wrap theme={null}
  curl \
    -H "x-ti-app-id: <your-app-id>" \
    -H "x-ti-secret-code: <your-secret-code>" \
    "https://docflow.textin.ai/api/app-api/sip/platform/v2/category/tables/list?workspace_id=<your-workspace-id>&category_id=<category-id>"
  ```

  ```python Python icon=python expandable lines theme={null}
  import requests

  ti_app_id = "<your-app-id>"
  ti_secret_code = "<your-secret-code>"
  workspace_id = "<your-workspace-id>"
  category_id = "<category-id>"

  host = "https://docflow.textin.ai"
  url = "/api/app-api/sip/platform/v2/category/tables/list"

  resp = requests.get(
      url=f"{host}{url}",
      params={
          "workspace_id": workspace_id,
          "category_id": category_id
      },
      headers={
          "x-ti-app-id": ti_app_id,
          "x-ti-secret-code": ti_secret_code,
      },
      timeout=30,
  )

  result = resp.json()
  if result.get("code") == 200:
      tables = result.get("result", {}).get("tables", [])
      print(f"Found {len(tables)} tables")
      for table in tables:
          print(f"Table ID: {table.get('id')}, Name: {table.get('name')}")
          print(f"  Prompt: {table.get('prompt')}")
          print(f"  Multi-table merge: {table.get('collect_from_multi_table')}")
  else:
      print(f"Retrieval failed: {result.get('msg')}")
  ```
</CodeGroup>

**Request Parameters:**

* `workspace_id` (required): Workspace ID
* `category_id` (required): File category ID

**Response Example:**

```json theme={null}
{
  "code": 200,
  "msg": "success",
  "result": {
    "tables": [
      {
        "id": "table_123",
        "name": "Item Details",
        "prompt": "Please extract item name, quantity, and amount for each row",
        "collect_from_multi_table": true
      },
      {
        "id": "table_456",
        "name": "Fee Details",
        "prompt": "Please extract fee item and amount for each row",
        "collect_from_multi_table": false
      }
    ]
  }
}
```

## Add Table

Add table(s) under a specified file category:

<CodeGroup>
  ```bash curl icon=terminal wrap theme={null}
  curl -X POST \
    -H "x-ti-app-id: <your-app-id>" \
    -H "x-ti-secret-code: <your-secret-code>" \
    -H "Content-Type: application/json" \
    -d '{
      "workspace_id": "<your-workspace-id>",
      "category_id": "<category-id>",
      "tables": [
        {
          "name": "Item Details",
          "prompt": "Please extract item name, quantity, and amount for each row",
          "collect_from_multi_table": true
        }
      ]
    }' \
    "https://docflow.textin.ai/api/app-api/sip/platform/v2/category/tables/batch_add"
  ```

  ```python Python icon=python expandable lines theme={null}
  import requests

  ti_app_id = "<your-app-id>"
  ti_secret_code = "<your-secret-code>"
  workspace_id = "<your-workspace-id>"
  category_id = "<category-id>"

  host = "https://docflow.textin.ai"
  url = "/api/app-api/sip/platform/v2/category/tables/batch_add"

  payload = {
      "workspace_id": workspace_id,
      "category_id": category_id,
      "tables": [
          {
              "name": "Item Details",
              "prompt": "Please extract item name, quantity, and amount for each row",
              "collect_from_multi_table": True  # Whether to merge multiple tables in document
          }
      ]
  }

  resp = requests.post(
      url=f"{host}{url}",
      json=payload,
      headers={
          "x-ti-app-id": ti_app_id,
          "x-ti-secret-code": ti_secret_code,
      },
      timeout=30,
  )

  result = resp.json()
  if result.get("code") == 200:
      table_id = result.get("result", {}).get("table_id")
      print(f"Table created successfully, ID: {table_id}")
  else:
      print(f"Creation failed: {result.get('msg')}")
  ```
</CodeGroup>

**Request Parameters:**

* `workspace_id` (required): Workspace ID
* `category_id` (required): File category ID
* `tables` (required): Array of table objects, each containing:
  * `name` (required): Table name, max length 50
  * `prompt` (optional): Semantic extraction prompt for table, max length 200
  * `collect_from_multi_table` (optional): Whether to merge multiple tables, default is false

**Response Example:**

```json theme={null}
{
  "code": 200,
  "msg": "success",
  "result": {
    "table_id": "table_new_789"
  }
}
```

<Note>
  **Multi-table merge explanation**: When a document contains multiple tables with the same structure, enabling `collect_from_multi_table` will merge them into one table result. For example, if invoice item details span across multiple pages, enabling multi-table merge will combine all pages of details into one.
</Note>

## Update Table

Update information for specified table(s):

<CodeGroup>
  ```bash curl icon=terminal wrap theme={null}
  curl -X POST \
    -H "x-ti-app-id: <your-app-id>" \
    -H "x-ti-secret-code: <your-secret-code>" \
    -H "Content-Type: application/json" \
    -d '{
      "workspace_id": "<your-workspace-id>",
      "category_id": "<category-id>",
      "tables": [
        {
          "table_id": "<table-id>",
          "name": "Updated Table Name",
          "prompt": "Updated prompt",
          "collect_from_multi_table": true
        }
      ]
    }' \
    "https://docflow.textin.ai/api/app-api/sip/platform/v2/category/tables/batch_update"
  ```

  ```python Python icon=python expandable lines theme={null}
  import requests

  ti_app_id = "<your-app-id>"
  ti_secret_code = "<your-secret-code>"
  workspace_id = "<your-workspace-id>"
  category_id = "<category-id>"

  host = "https://docflow.textin.ai"
  url = "/api/app-api/sip/platform/v2/category/tables/batch_update"

  payload = {
      "workspace_id": workspace_id,
      "category_id": category_id,
      "tables": [
          {
              "table_id": "<table-id>",
              "name": "Updated Table Name",
              "prompt": "Updated prompt",
              "collect_from_multi_table": True
          }
      ]
  }

  resp = requests.post(
      url=f"{host}{url}",
      json=payload,
      headers={
          "x-ti-app-id": ti_app_id,
          "x-ti-secret-code": ti_secret_code,
      },
      timeout=30,
  )

  result = resp.json()
  if result.get("code") == 200:
      print("Table updated successfully")
  else:
      print(f"Update failed: {result.get('msg')}")
  ```
</CodeGroup>

**Request Parameters:**

* `workspace_id` (required): Workspace ID
* `category_id` (required): File category ID
* `tables` (required): Array of table objects, each containing:
  * `table_id` (required): Table ID
  * `name` (optional): Table name, max length 50
  * `prompt` (optional): Semantic extraction prompt for table, max length 200
  * `collect_from_multi_table` (required): Whether to merge multiple tables

## Delete Table

Delete specified table(s), supporting batch deletion:

<CodeGroup>
  ```bash curl icon=terminal wrap theme={null}
  curl -X POST \
    -H "x-ti-app-id: <your-app-id>" \
    -H "x-ti-secret-code: <your-secret-code>" \
    -H "Content-Type: application/json" \
    -d '{
      "workspace_id": "<your-workspace-id>",
      "category_id": "<category-id>",
      "table_ids": ["table_123", "table_456"]
    }' \
    "https://docflow.textin.ai/api/app-api/sip/platform/v2/category/tables/delete"
  ```

  ```python Python icon=python expandable lines theme={null}
  import requests

  ti_app_id = "<your-app-id>"
  ti_secret_code = "<your-secret-code>"
  workspace_id = "<your-workspace-id>"
  category_id = "<category-id>"

  host = "https://docflow.textin.ai"
  url = "/api/app-api/sip/platform/v2/category/tables/delete"

  payload = {
      "workspace_id": workspace_id,
      "category_id": category_id,
      "table_ids": ["table_123", "table_456"]
  }

  resp = requests.post(
      url=f"{host}{url}",
      json=payload,
      headers={
          "x-ti-app-id": ti_app_id,
          "x-ti-secret-code": ti_secret_code,
      },
      timeout=30,
  )

  result = resp.json()
  if result.get("code") == 200:
      print("Table deleted successfully")
  else:
      print(f"Deletion failed: {result.get('msg')}")
  ```
</CodeGroup>

**Request Parameters:**

* `workspace_id` (required): Workspace ID
* `category_id` (required): File category ID
* `table_ids` (required): Array of table IDs to delete

<Warning>
  Deleting a table will also delete all fields under it. Please proceed with caution.
</Warning>

## Table Field Management

After creating a table, you need to add fields to define the columns of the table. For table field management, please refer to the "Add Table Field" section in the [Fields Management](./fields_management) documentation.

### Example: Create Table and Add Fields

```python Python icon=python expandable theme={null}
import requests

ti_app_id = "<your-app-id>"
ti_secret_code = "<your-secret-code>"
workspace_id = "<your-workspace-id>"
category_id = "<category-id>"
host = "https://docflow.textin.ai"

# 1. Create table
table_resp = requests.post(
    url=f"{host}/api/app-api/sip/platform/v2/category/tables/batch_add",
    json={
        "workspace_id": workspace_id,
        "category_id": category_id,
        "tables": [
            {
                "name": "Item Details",
                "prompt": "Please extract item name, quantity, and amount for each row",
                "collect_from_multi_table": True
            }
        ]
    },
    headers={
        "x-ti-app-id": ti_app_id,
        "x-ti-secret-code": ti_secret_code,
    },
)
table_id = table_resp.json()["result"]["table_id"]
print(f"Table created successfully, ID: {table_id}")

# 2. Add fields to table (batch)
field_resp = requests.post(
    url=f"{host}/api/app-api/sip/platform/v2/category/fields/batch_add",
    json={
        "workspace_id": workspace_id,
        "category_id": category_id,
        "table_id": table_id,  # Specify table ID
        "fields": [
            {"name": "Item Name", "description": "Name of goods or services"},
            {"name": "Quantity", "description": "Item quantity"},
            {"name": "Unit Price", "description": "Item unit price"},
            {"name": "Amount", "description": "Item amount"}
        ]
    },
    headers={
        "x-ti-app-id": ti_app_id,
        "x-ti-secret-code": ti_secret_code,
    },
)
result = field_resp.json()
if result.get("code") == 200:
    print("All fields created successfully")
else:
    print(f"Field creation failed: {result.get('msg')}")

print("Table and fields creation completed")
```

## Table Configuration

### Table Properties

* **name**: Table name, required
* **prompt**: Semantic extraction prompt for table, used to guide AI in table extraction
* **collect\_from\_multi\_table**: Whether to merge multiple tables

### Multi-table Merge Scenarios

The following scenarios are suitable for enabling multi-table merge:

1. **Cross-page tables**: Table content spans across multiple pages
2. **Repeated tables**: Multiple tables with the same structure exist in the document
3. **Segmented tables**: Tables are separated by other content

Example: If invoice item details span across multiple pages, enabling multi-table merge will combine all pages of item details into one complete table result.

## Next Steps

* Learn [Fields Management](./fields_management) - Add fields to tables
* Learn [Samples Management](./samples_management) - Manage sample files for file categories
* Return to [Category Quickstart](./quickstart) - View basic file category operations