> ## 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.

# Importação em massa de itens

> Importação em lote de itens para uma lista, com flag opcional replaceExisting e modos de validação, projetada para grandes volumes.

## Visão geral

Importa muitos itens em uma única requisição (validação por linha). Destinado a **carga em massa** ou migrações.

## Endpoint

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

## Autenticação

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

## Corpo da solicitação

<ParamField body="items" type="array" required>
  Each item may include: `primaryValue`, `secondaryValue`, `searchKeys`, `category`, `riskScore`, `severity` (`low` | `medium` | `high` | `critical`), `reason`, `sourceReference`, `itemData`, `metadata`, `isActive`, plus passthrough fields as accepted by the API.
</ParamField>

<ParamField body="skipValidationErrors" type="boolean">
  When true, continues importing valid rows while collecting errors for invalid ones (behavior as implemented server-side).
</ParamField>

<ParamField body="replaceExisting" type="boolean">
  When true, replaces existing matches according to server merge rules.
</ParamField>

## Resposta

Usually `200` with `successful`, `errors`, and per-row `errorDetails` for partial failures.

## Permissões

Requires **bulk import** permission for data lists. **Global** lists accept writes only from **system administrators**.