API de Datasets

Um dataset é uma tabela sua dentro do CrazyLeads: você define as colunas, envia as linhas e consulta de volta. Serve para trazer dados que não vêm de uma fonte conectada — uma planilha de vendas, o resultado de um sistema interno, uma lista de produtos.

Autenticação

Toda chamada leva uma chave de dataset no cabeçalho Authorization. A chave é criada no painel e vale para um projeto. Nos endpoints de dados — os que leem, enviam e alteram linhas — ela carrega ainda a permissão por dataset: read para ler e write para escrever; pedir acima disso devolve 403, dizendo qual permissão faltou e em qual dataset. Os endpoints que mexem na estrutura do dataset exigem a chave e são operação administrativa: use uma chave dedicada a eles e não a distribua junto com a que só lê.

Primeira chamada

curl https://apiserver.crazyleads.com.br/api/datasets/ \
  -H "Authorization: Bearer dskey_SUA_CHAVE_AQUI"

Gerenciar o dataset

Endpoint	O que faz	Permissão
GET /	Lista os datasets do projeto	`chave`
POST /	Cria um dataset	`chave`
GET /{id}/	Detalha um dataset	`chave`
PATCH /{id}/	Renomeia ou altera o dataset	`chave`
DELETE /{id}/	Apaga o dataset e as linhas dele	`chave`
GET /{id}/schema/	Colunas, tipos e versão em vigor	`chave`
POST /{id}/columns/	Acrescenta uma coluna	`chave`
PATCH /{id}/columns/{coluna}/	Altera uma coluna	`chave`
DELETE /{id}/columns/{coluna}/	Remove uma coluna	`chave`
POST /{id}/publish/	Publica a versão corrente do schema	`chave`
POST /{id}/rollback/	Volta para uma versão anterior	`chave`
GET /{id}/usage/	Uso e contagens do dataset	`chave`

Enviar dados

Endpoint	O que faz	Permissão
POST /{slug}/rows/bulk-upsert/	Insere ou atualiza linhas em lote	`write`
POST /{slug}/rows/bulk-delete/	Remove linhas em lote	`write`
POST /{slug}/csv/upload/	Envia um CSV	`write`

Consultar

Endpoint	O que faz	Permissão
GET /{slug}/rows/	Lê as linhas, com filtro e paginação	`read`
PATCH /{slug}/rows/	Atualiza linhas que casem com um filtro	`write`
GET /{slug}/rows/export/	Exporta as linhas	`read`
GET /{slug}/summary/	Resumo do conteúdo do dataset	`read`

Enviar linhas em lote

A chave do upsert é sempre o campo id: mandou um id que já existe, atualiza; mandou um que não existe, insere com aquele identificador; não mandou, insere com um identificador novo. Isso significa que reenviar o mesmo lote não duplica linha — desde que você seja dono dos ids. Se deixar o sistema gerar, reenviar cria linhas novas.

POST /{slug}/rows/bulk-upsert/

{
  "rows": [
    { "id": "8f14e45f-ceea-467a-9e6b-1f0e8f0b5d21",
      "produto": "Plano Anual",
      "valor": 1990.00,
      "vendido_em": "2025-06-15T10:30:00+00:00" },
    { "produto": "Plano Mensal", "valor": 199.00 }
  ]
}

O parâmetro upsert_keys foi descontinuado e é ignorado — se o seu código ainda o envia, pode tirar sem mudar o resultado.

Versões do schema

Acrescentar ou mudar uma coluna altera o schema em rascunho. publish torna esse rascunho a versão em vigor, e rollback volta para uma anterior. Consulte schema antes de uma carga grande: enviar coluna que não existe na versão em vigor é erro, não é criação silenciosa.

Limites

Operação	Limite	Pico
Leitura	3.000 por minuto	300
Escrita	600 por minuto	100
Importação de CSV	10 por hora	2

Os limites valem por chave. Ao estourar, a resposta é 429 com o tempo de espera — respeite-o em vez de repetir em seguida, ou a espera só aumenta.