A API estável do Steel para scripts, CI e o Steel CLI. Token pessoal, escopos, módulos, erros, paginação por cursor, limites e a política de estabilidade.
Nesta página
A API pública v1 é um recorte estável do Steel, em /api/v1/..., feito para quem
automatiza: scripts, pipelines de CI, integrações internas e o steel CLI.
O resto da API (/api/workspaces/<id>/...) é a que o aplicativo usa e pode
mudar a cada versão; a v1 não.
Recurso
O que dá para fazer
Página
Conta e login
Ver o token em uso, login do CLI pelo navegador, revogar
A referência completa, com cada rota, parâmetro e código de erro, está em
Referência da API v1. O documento OpenAPI fica em
/dev/api/v1/openapi.json; é dele que o SDK TypeScript @steel-so/sdk é
gerado. O Steel CLI e o SDK têm guias próprios; aqui
cada operação aparece nas três formas: curl, steel e SDK.
Antes da primeira chamada
Os exemplos usam duas variáveis de ambiente, as mesmas que o CLI lê:
O SDK nunca lança exceção por erro HTTP ou de rede: toda chamada resolve em
{ ok: true, status, data } ou { ok: false, error: { status, code, message } }.
O data já vem sem o envelope.
Token pessoal
Toda chamada leva um ( seguido de 43 caracteres)
no cabeçalho :
O cookie de sessão do aplicativo não vale na v1, nem a chave crm_live_ do
CRM, nem o token do MCP (stl_at_).
Criar um token na tela
No menu do seu avatar, abra Configurações e vá à aba Segurança.
Em Tokens de API, clique em Criar token.
Preencha:
Nome: para você reconhecer depois (por exemplo, "Deploy no GitHub
Actions");
Workspace: o token vale só para ele;
Módulos: ServiceDesk, CRM e/ou Comunicação. Aparecem só os módulos
habilitados no workspace;
Nível de acesso: Somente ler (api:read) ou Ler e alterar
(api:read + api:write);
Validade: 7, 30, 90 (padrão) ou 180 dias, ou 1 ano.
Clique em Criar token. A janela Token criado mostra o valor uma
vez só: copie e guarde num cofre de segredos (no GitHub Actions, um
secret do repositório).
A lista mostra cada token com o workspace, os módulos, o nível de acesso, a
validade e o último uso. Revogar corta o acesso na chamada seguinte. Cada
pessoa tem até 50 tokens ativos; o 51º responde
422 API_TOKEN_LIMIT_REACHED.
Criar um token pelo terminal
steel login faz o mesmo pelo navegador, sem copiar nada: o CLI mostra um
código, você confirma em /device escolhendo workspace, módulos e nível de
acesso, e o token (chamado Steel CLI — <nome da máquina>) fica no chaveiro
do sistema. Detalhes do fluxo em Conta e login.
O que o token pode fazer
Cada token pertence a você e a um workspace. A chamada roda com as suas
permissões nesse workspace: o papel e o perfil de acesso valem como no
aplicativo, e cada alteração entra na auditoria com source: api e o id do
token.
Escopo
Permite
api:read
Ler. Todo token tem
api:write
Criar e alterar. Sem ele, escritas respondem 403 API_TOKEN_SCOPE_REQUIRED
O token só alcança os módulos escolhidos na criação que continuam
habilitados no workspace. Uma rota de outro módulo responde
403 API_TOKEN_MODULE_NOT_ALLOWED. Se um administrador desligar um módulo, o
token perde aquele módulo na hora; religado, volta a valer.
As rotas de webhooks (/api/v1/webhooks/...) não dependem de módulo, mas
exigem que você seja OWNER ou ADMIN do workspace.
GET /api/v1/me mostra os escopos, os módulos e a validade do token em uso.
A resposta traz data.items e data.nextCursor. nextCursor: null é a última
página. O cursor é opaco: não monte nem altere; um cursor inválido responde
422 VALIDATION_ERROR.
No CLI, --all percorre todas as páginas; --limit e --cursor pedem uma
só:
steel crm lead list --all --json | jq '.items | length'
No SDK, collectAll faz o laço e para no primeiro erro:
import { collectAll } from '@steel-so/sdk'
const all = await collectAll((cursor) =>
steel.crm.leads.list({ limit: 100, cursor }),
)
if (all.ok) console.log(all.data.items.length)
Importar leads de um CSV
POST /api/v1/crm/leads/import recebe o próprio CSV como corpo
(Content-Type: text/csv), até 5.000 linhas e 5 MB, e responde quantos leads
foram criados, quantos já existiam (skipped) e quais linhas foram recusadas.
As colunas aceitas, os exemplos em curl, CLI e SDK e os erros estão em
CRM na API v1.
Limites
Cada token tem 300 requisições a cada 60 segundos, e o usuário dono do token
mantém o limite de sempre (100 requisições por minuto, somando aplicativo e
API). Ao passar, a resposta é 429 RATE_LIMITED com o cabeçalho Retry-After
em segundos e o mesmo valor em error.details.retryAfterSeconds. O SDK põe
esse número em error.retryAfterSeconds. Veja
Limites de requisição.
Outros limites que você encontra na v1:
O quê
Limite
Importação de leads
5.000 linhas e 5 MB por chamada
Envio de template do WhatsApp
20 mensagens por minuto por conexão, além da cota mensal do plano
Endpoints de webhook
20 por workspace
Log de entregas de webhook
30 dias
Login do CLI (/api/v1/auth/device)
10 inícios a cada 10 minutos por IP; o código vale 10 minutos
Validade de um token
1 ano no máximo; 90 dias por padrão
Estabilidade e depreciação
Na v1:
nada é removido nem muda de tipo, e nenhum campo de entrada passa a ser
obrigatório;
campos, parâmetros opcionais, rotas e códigos de erro novos podem aparecer a
qualquer momento. Ignore o que o seu código não conhece;
uma rota só sai depois de 6 meses respondendo com os cabeçalhos
Deprecation e Sunset e com aviso no changelog.
O build do Steel verifica isso a cada mudança: se o documento da v1 perde um
campo ou muda um tipo, o build falha. Uma mudança incompatível, quando
necessária, vira uma nova versão da API (a v2), e a v1 continua no ar durante a
transição.
Solução de problemas
Sintoma
Causa provável e correção
401 logo na primeira chamada
Faltou Bearer antes do token, o token tem espaço ou quebra de linha, ou é um token de outro ambiente. Teste com GET /api/v1/me
401 num token que funcionava
Venceu, foi revogado (por você ou por um administrador) ou você saiu do workspace. Gere outro
403 API_TOKEN_MODULE_NOT_ALLOWED numa rota que deveria funcionar
O token foi criado sem o módulo, ou o módulo foi desligado depois. GET /api/v1/me mostra os módulos que valem agora
403 FORBIDDEN só nas escritas
Falta o aceite dos termos (entre no Steel uma vez) ou o seu papel não permite a ação no aplicativo
404 num id que existe
O registro é de outro workspace. Cada token vale para um só
422 com Cursor inválido
O cursor foi montado à mão ou veio de outra lista. Use o nextCursor da mesma rota, com os mesmos filtros
429 em rajadas
Distribua as chamadas ou use páginas maiores (limit=100). Lembre que o aplicativo aberto também consome o limite do usuário
A lista de chamados volta vazia
Sem status, só os abertos aparecem; e quem é solicitante vê só os próprios
