Começando

A API Externa v1 do Growth OS dá acesso, por chave, ao que um workspace já tem: contatos, funil, agenda, tarefas, interações, equipe, webhooks e (por chave da conta Accelera) uso de aluno na plataforma. Toda rota nova entra em /api/v1 como aditivo — nada aqui quebra sem virar /api/v2.

O endereço base é https://api.staging.growthaisystem.com/api/v1, e é o que todos os exemplos desta documentação já usam. O documento OpenAPI cru, se você gera cliente a partir dele, está em https://api.staging.growthaisystem.com/api/v1/openapi.json.

1. Crie uma chave

Em Acessos → Integrações → Chaves de API, dentro do workspace (só o dono enxerga essa aba), clique em "Criar chave de API". Marque só os escopos que a integração precisa — o que não estiver marcado responde 403 forbidden_scope, com a mensagem nomeando o que falta. O token completo (gos_…) aparece uma única vez: guarde-o antes de fechar a tela, não há rota que o devolva depois.

A chave dá acesso ao workspace inteiro dentro dos escopos marcados: trate como segredo de servidor. Ela não vai para navegador, app mobile nem repositório.

Se o seu caso é outro — um app de terceiro em que cada usuário entra com a conta dele, e não uma integração do próprio workspace —, a credencial não é esta: veja login de usuário (OAuth2).

2. A primeira leitura

Se você marcou contacts.read:

curl "https://api.staging.growthaisystem.com/api/v1/contacts?limit=1" \
  -H "Authorization: Bearer gos_SEU_TOKEN_AQUI"

Resposta esperada (200) — o envelope de toda listagem paginada é { data, nextCursor }:

{
  "data": [
    {
      "id": "c_01HXY...",
      "name": "Maria Souza",
      "phone": "5511988887777",
      "email": "maria@exemplo.com",
      "company": null,
      "tags": ["canal:lp"],
      "status": "active",
      "origin": "api",
      "customFields": {},
      "createdAt": "2026-09-13T18:04:11.231Z",
      "updatedAt": "2026-09-13T18:04:11.231Z",
      "url": "https://app.suamarca.com.br/crm/contatos?contactId=c_01HXY..."
    }
  ],
  "nextCursor": null
}

Workspace novo devolve {"data": [], "nextCursor": null}: isso é sucesso, não erro.

3. A primeira escrita

curl -X POST "https://api.staging.growthaisystem.com/api/v1/contacts/upsert" \
  -H "Authorization: Bearer gos_SEU_TOKEN_AQUI" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f1c0a9e-6a1e-4c2f-9f3a-1c0a9e6a1e4c" \
  -d '{"name":"Maria Souza","phone":"5511988887777","email":"maria@exemplo.com","tags":["origem:site"]}'

Para lead de formulário, prefira /contacts/upsert a /contacts: ele procura o contato por telefone (e depois por e-mail), preenche o que está vazio, soma as etiquetas e não apaga nada. A resposta traz created: true|false dizendo o que aconteceu — 201 quando criou, 200 quando atualizou (ou quando a escrita foi uma repetição). Sem phone e sem email a resposta é 400: não haveria por onde deduplicar.

Antes de automatizar retry, leia idempotência: a API deduplica escrita repetida mesmo sem o header Idempotency-Key, numa janela de 60 segundos.

4. O mapa dos recursos

Cada rota documenta a si mesma na referência interativa — descrição, parâmetros, exemplo e "testar" direto no navegador. Para chegar em qualquer uma delas sem passar pelo menu, ⌘ K (ou Ctrl K) abre a busca desta documentação.

5. O que ler em seguida

Nesta ordem, que é a que evita retrabalho: autenticação (os escopos), convenções (datas, telefone, campos, null), paginação e datas, erros, limites de uso, idempotência e webhooks.

Fora dessa linha, e só se o seu app entra com a conta da pessoa em vez de uma chave de servidor: login de usuário (OAuth2).