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

# Criar Instância

> POST /v1/instances — Registra uma nova instância de chamada no WhatsApp

`POST /v1/instances`

Cria uma nova instância do WhatsApp. Após a criação, [vincule um número de telefone](/api-reference/instances/configure) escaneando o QR code.

## Requisição

### Cabeçalhos

| Cabeçalho       | Valor              |
| --------------- | ------------------ |
| `Authorization` | `Bearer <token>`   |
| `Content-Type`  | `application/json` |

### Corpo

| Campo      | Tipo     | Obrigatório | Descrição                            |
| ---------- | -------- | ----------- | ------------------------------------ |
| `name`     | `string` | Sim         | Um rótulo para esta instância        |
| `metadata` | `object` | Não         | Metadados arbitrários em chave-valor |

```json theme={null}
{
  "name": "sales-team-a",
  "metadata": {
    "region": "us-east"
  }
}
```

## Resposta `201`

Retorna o objeto da instância criada.

| Campo        | Tipo     | Descrição                               |
| ------------ | -------- | --------------------------------------- |
| `id`         | `string` | ID único da instância (prefixo `inst_`) |
| `name`       | `string` | Rótulo da instância                     |
| `status`     | `string` | Sempre `CREATED` na criação             |
| `metadata`   | `object` | Metadados fornecidos                    |
| `created_at` | `string` | Timestamp ISO 8601                      |
| `updated_at` | `string` | Timestamp ISO 8601                      |

```json theme={null}
{
  "id": "inst_abc123",
  "name": "sales-team-a",
  "status": "CREATED",
  "metadata": { "region": "us-east" },
  "created_at": "2026-03-01T10:00:00Z",
  "updated_at": "2026-03-01T10:00:00Z"
}
```

## Erros

| Código | Descrição                 |
| ------ | ------------------------- |
| `400`  | `name` está ausente       |
| `401`  | Token ausente ou inválido |

## Exemplo

```bash theme={null}
curl -X POST https://cawme.com/api/v1/instances \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "sales-team-a",
    "metadata": { "region": "us-east" }
  }'
```