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

# Add items to list

> Append one or more items to a specific data list by UUID with primaryValue, searchKeys, and optional itemData payload — POST /data-lists/{id}/items.

## Overview

Adds one or more items to a **specific** list identified by UUID. Requires permission to update the list.

## Endpoint

```
POST https://api.gu1.ai/data-lists/{id}/items
```

## Authentication

```bash theme={null}
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
```

## Request Body

<ParamField body="items" type="array" required>
  Each element:

  * `primaryValue` (string, required)
  * `searchKeys` (string\[], optional)
  * `category` (string, optional)
  * `riskScore` (number, optional)
  * `itemData` (object, optional)
  * `metadata` (object, optional)
</ParamField>

<ParamField body="options" type="object">
  * `batchSize` (number, optional)
  * `ignoreDuplicates` (boolean, optional)
  * `updateExisting` (boolean, optional)
</ParamField>

## Notes

* For **large** uploads with richer per-row fields, prefer **[Bulk import items](/en/api-reference/data-lists/bulk-import-items)** (`POST /data-lists/{id}/items/bulk`).
* Shortcut **`POST /data-lists/{type}/items`** adds to the **first active list** of that type (oldest by default). Prefer **list id** when you have multiple lists per type.

## Response

`201` with counts (`processed`, `errors`, `duplicates`, etc.) on success.