For AI agents: the complete documentation index is available at https://docs.clickmax.io/llms.txt, the full documentation bundle is available at https://docs.clickmax.io/llms-full.txt, and this page is available as Markdown at https://docs.clickmax.io/reference/api/index.md.
  • Português

      • API da Clickmax

      A API pública da Clickmax responde em https://mcp.clickmax.io/api/v0. Cada requisição age sobre um workspace e é autenticada pela chave de API desse workspace.

      Referência interativaExplore a API por endpointConsulte parâmetros, exemplos de requisição e schemas de resposta em uma única tela.Abrir referência
      A v0 ainda é instável

      O 0 em /api/v0/ indica que esta versão ainda pode mudar. Endpoints, parâmetros e respostas podem ser alterados sem aviso prévio. Consulte sempre o schema publicado antes de atualizar sua integração.

      Bibliotecas

      Em JavaScript e TypeScript, use o pacote @clickmax/public-sdk. Ele traz um método tipado para cada endpoint e devolve os erros já no formato descrito em Erros. Em outras linguagens, chame a API por HTTP, como no exemplo em cURL.

      Os dois exemplos abaixo fazem a mesma requisição: listam as tags do workspace.

      SDK TypeScript
      cURL
      npm install @clickmax/public-sdk
      import { Clickmax } from '@clickmax/public-sdk'

const clickmax = new Clickmax(process.env.CLICKMAX_API_KEY!)

const result = await clickmax.tags.list()

if (result.ok) {
  console.log(result.value.data)
} else {
  const { type, code, requestId } = result.error
  console.error('tags.list falhou', { type, code, requestId })
}

      Instalação, opções e tratamento de erros do pacote estão em Como usar o SDK TypeScript da Clickmax.

      Autenticação

      Proprietários e administradores criam e revogam chaves em Configurações > Conexões > API. Cada workspace pode manter até 5 chaves. Se não achar a tela, pergunte ao Max onde gerar a chave de API: o botão dele abre direto nessa aba.

      A chave é exibida somente após a criação e não pode ser consultada novamente. Para substituir uma chave ou alterar seus endereços IP, revogue a anterior e crie outra.

      O prefixo identifica o ambiente: cxp_ para produção, cxs_ para staging e cxd_ para desenvolvimento.

      Uma chave sem endereços IP permitidos funciona a partir de qualquer IP. Quando a lista é preenchida, a API aceita somente os endereços IPv4 ou IPv6 exatos informados.

      Envie a chave em todas as requisições:

      Authorization: Bearer <chave-da-api>

      A chave age em nome do workspace inteiro. Guarde-a em um servidor, em variável de ambiente ou em um gerenciador de segredos, e nunca a inclua em código que roda no navegador ou em aplicativos.

      Uma chave ausente, revogada, de outro ambiente ou usada a partir de um IP fora da lista recebe a mesma resposta 401 com o código unauthorized. A resposta não diz qual dessas condições falhou.

      As chaves da API não autenticam conexões MCP. O MCP continua usando OAuth.

      Erros

      Quando uma requisição falha, a API responde com status 4xx ou 5xx e um corpo JSON como este:

      {
  "error": "Rate limit exceeded.",
  "type": "rate_limit",
  "code": "rate_limit_exceeded",
  "requestId": "8f1c2a3b4c5d6e7f-GRU"
}
      CampoConteúdo
      errorMensagem legível. O texto pode mudar entre versões, então não o use para decidir o que fazer.
      typeCategoria do erro. Os valores estão na tabela abaixo.
      codeMotivo específico em minúsculas com sublinhado, como invalid_input. Quando não há um motivo mais específico, repete o type.
      requestIdIdentificador da requisição. Informe esse valor ao suporte.
      issuesLista de problemas de validação, presente quando code é invalid_input. Cada item tem path (o caminho do campo), message e code.
      capabilityPermissão que faltou, presente quando code é missing_permission.

      Decida o tratamento pelo type e use o code para casos específicos. Se receber um type que não está listado aqui, trate o erro pelo status HTTP.

      typeStatus HTTPSignificado e o que fazer
      invalid_request400, 405, 413, 415, 422 e qualquer 4xx que não esteja nas outras linhasA requisição foi recusada como está. Corrija os parâmetros ou o corpo antes de enviar de novo.
      authentication401A chave está ausente ou não é aceita. Confira a chave, o ambiente e a lista de IPs.
      permission403A chave não pode executar essa operação. Veja o code e o campo capability.
      not_found404, 410O endpoint ou o registro não existe. Confira o caminho e os IDs enviados.
      conflict409, 412A operação não combina com o estado atual do registro. Leia o registro de novo e ajuste a requisição.
      rate_limit429O workspace passou do limite de requisições. Aguarde o número de segundos indicado em Retry-After.
      api408, 500, 502, 504 e outros 5xxFalha do lado da Clickmax. Tente de novo depois de alguns segundos e, se continuar, informe o requestId ao suporte. Antes de repetir uma operação de escrita, confira se ela já não foi aplicada.

      Estes são os valores de code mais comuns:

      codeStatusQuando acontece
      unauthorized401A chave não foi aceita. Os casos estão em Autenticação.
      rate_limit_exceeded429O workspace passou de 100 requisições em 10 segundos.
      route_not_found404O caminho não corresponde a nenhum endpoint da v0.
      method_not_allowed405O endpoint existe, mas espera outro método HTTP. O cabeçalho Allow da resposta indica o método certo.
      invalid_json400O corpo da requisição não é um JSON válido.
      invalid_json_object400A entrada não é um objeto JSON.
      invalid_input400A entrada não segue o schema do endpoint. Veja os itens de issues.
      validation_failed400Um serviço interno da Clickmax recusou a entrada depois que ela passou pelo schema do endpoint. O campo error descreve o problema, e não há lista issues.
      missing_permission403A chave não tem a permissão que a operação exige. O campo capability indica qual.
      module_disabled403O módulo dessa operação está desativado no workspace.
      upstream_error502Um serviço interno da Clickmax falhou.
      upstream_unreachable502Não foi possível falar com um serviço interno da Clickmax.
      upstream_timeout504Um serviço interno da Clickmax demorou demais para responder.
      internal_error500Erro inesperado na API.

      Outros endpoints podem devolver códigos próprios, sempre em minúsculas com sublinhado.

      Limite de requisições

      A API pública aceita até 100 requisições a cada 10 segundos por workspace. Todas as chaves do workspace compartilham esse limite.

      Acima disso, a API responde 429 com type rate_limit, code rate_limit_exceeded e o cabeçalho Retry-After: 10, que é o número de segundos a esperar antes da próxima tentativa. Se o erro se repetir, reduza as requisições simultâneas.

      Outros recursos

      RecursoQuando usar
      Schema OpenAPI YAMLConsultar o contrato atual, gerar clientes ou fornecer o schema diretamente a um agente de IA.
      Pacote @clickmax/public-sdk no npmInstalar o SDK TypeScript e consultar as versões publicadas.
      MCP da ClickmaxConectar clientes de IA compatíveis com MCP e OAuth.