---
title: "Para agentes de IA"
slug: agents
group: "Primeiros passos"
source: https://linkzap.ia.br/developers/agents
openapi: https://linkzap.ia.br/openapi.json
---

# Para agentes de IA

Se você é uma IA: este é o roteiro inteiro para operar o LinkZap sozinha. Você só precisa pedir uma credencial ao usuário.

## 1. Peça a credencial

1. **Chave de API (o caminho mais simples).** Peça ao usuário: *"Abra o LinkZap › Configurações › Integrações › Conectar uma IA e me passe o bloco que aparecer"*. A chave começa com `lz_` e vale como ele: você pode no LinkZap exatamente o que ele pode.
2. **Login (OAuth), se você é um cliente MCP** (claude.ai, ChatGPT): conecte `https://linkzap.ia.br/mcp`. O servidor anuncia a autorização sozinho (401 com `WWW-Authenticate`), e o usuário entra e escolhe a organização.

> [!WARNING]
> **Nunca no navegador**
>
> A chave dá acesso à conta inteira de quem a criou. Guarde-a só no seu ambiente de servidor e não a repita na conversa além do necessário.

## 2. Descubra o que dá para fazer

Confira a chave com `GET https://linkzap.ia.br/api/v1/me`. Depois liste as ações com `GET https://linkzap.ia.br/api/v1/actions` (ou o catálogo público em `https://linkzap.ia.br/actions.json`, que dá para ler antes de ter a chave). Cada ação tem um nome `área.verbo` e `GET /api/v1/actions/{nome}` devolve o JSON Schema da entrada.

Comando — Descobrir:

```bash
curl https://linkzap.ia.br/api/v1/actions?area=contacts -H "Authorization: Bearer lz_SUA_CHAVE"

curl https://linkzap.ia.br/api/v1/actions/tags.create -H "Authorization: Bearer lz_SUA_CHAVE"
```

## 3. Execute

Comando — Executar:

```bash
curl -X POST https://linkzap.ia.br/api/v1/actions/tags.create \
  -H "Authorization: Bearer lz_SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Cliente VIP", "color": "success" }'
```

- Sucesso: `200` com `{ "data": … }`. Recusa: `{ "error": "…" }` em português, com o status: `422` (entrada inválida, com `issues`), `403` (sem permissão), `404` (não existe).
- Leia antes de escrever: a maioria das ações pede ids que vêm de uma leitura (`contacts.list`, `pipelines.list`, `channels.list`…).
- Fluxos e agentes se editam lendo a definição (`flows.get`, `agents.get`), mudando e gravando com a MESMA `version`. Agente só atende depois de `agents.publish`.
- Freio: o mesmo da API. Um 429 traz `Retry-After`.

Por MCP é igual: as ferramentas `listActions`, `describeAction` e `runAction` fazem os três passos, ao lado das operações diretas da API.

## O que fica de fora

Apagar a organização, assinar ou cancelar o plano, e a conta pessoal (senha, foto) só pelo painel, por quem é dono deles. Criar a conta também é no site.