API e MCP

Acesse o Point11 pelo seu próprio software, assistente de IA ou terminal.

Visão geral#

O servidor MCP, a API e a ferramenta de linha de comando fazem o que você faz no painel: leem suas campanhas e resultados e iniciam o mesmo trabalho.

  • Servidor MCP: conecte o Claude, o ChatGPT ou outro assistente de IA.
  • API: chame o Point11 do seu próprio código em https://point11.ai/api/v1.
  • CLI: use a API no seu terminal.

Entre para abrir a referência da API; ela está disponível para membros de uma organização da Point11. Ela lista cada solicitação, o que recebe e o que retorna, e quais ações do painel o servidor MCP, a API e a CLI alcançam. Para testar anúncios e outros criativos com os gêmeos digitais dos seus clientes, veja Teste criativos com a API.

Conecte um assistente de IA#

Use esta URL do servidor MCP: https://point11.ai/api/mcp. Entre no Point11 e aprove o acesso quando solicitado. Se você faz parte de mais de uma organização, diga ao seu assistente qual usar. Para se conectar com uma chave de API, siga as etapas do seu cliente abaixo.

Para dar ao seu assistente apenas os produtos que você usa, conecte-se com uma chave de API e adicione os nomes deles à URL em letras minúsculas, separados por vírgulas, por exemplo https://point11.ai/api/mcp?products=discovery,inspector. Uma lista menor de ferramentas deixa mais espaço para o seu assistente trabalhar. Para entrar no Point11, use exatamente a URL acima, sem nada depois de /api/mcp. O Point11 lista apenas a versão atual de cada ferramenta; um assistente que ainda usa uma versão mais antiga continua funcionando.

Business e Alpha têm a maior quantidade de ferramentas, então você também pode adicionar apenas uma parte de qualquer um deles: o produto, um ponto e a parte, por exemplo business.customers. Business tem profiles, customers, crm, goals, products, measurement e google-ads. Alpha tem chat, projects, files, workflows, ads, brand-kits, advisor e connectors. Combine produtos e partes como quiser, por exemplo https://point11.ai/api/mcp?products=discovery,business.customers. Se o seu assistente procura ferramentas conforme precisa delas, ele ainda pode usar um produto inteiro ou o servidor completo.

Registros e clientes podem ler a descrição do servidor em https://point11.ai/api/mcp/server-card.

Claude na web e no desktop#

  1. Abra Customize > Connectors e depois + > Add custom connector.
  2. Use o nome Point11, insira exatamente https://point11.ai/api/mcp e selecione Add, depois Connect.
  3. Em uma conversa, abra + > Connectors e habilite o Point11.

Nos planos Team e Enterprise, um proprietário precisa primeiro adicionar o conector em Organization settings > Connectors. Consulte o guia de conectores do Claude.

Claude Code#

Execute no terminal:

bash
claude mcp add --transport http point11 https://point11.ai/api/mcp

Depois, abra o Claude Code, execute /mcp e selecione Point11 para autenticar. Para usar uma chave de API, adicione-a como cabeçalho:

bash
claude mcp add --transport http point11 https://point11.ai/api/mcp \
  --header "Authorization: Bearer $POINT11_API_KEY"

Consulte o guia de MCP do Claude Code.

ChatGPT na web#

  1. Abra Settings > Security and login e habilite Developer mode.
  2. Abra Plugins > +. Insira Point11, uma breve descrição e a URL do servidor em Connection e crie a conexão.
  3. Revise as ferramentas, inicie uma nova conversa e selecione Point11 no menu de ferramentas.

A disponibilidade depende das configurações da sua conta e do workspace. Consulte o guia de conexão da OpenAI.

ChatGPT desktop e Codex#

No aplicativo para desktop, abra Settings > MCP servers > Add server. Use o nome Point11, escolha Streamable HTTP e insira a URL do servidor. Salve, selecione Restart e depois Authenticate.

Para a CLI do Codex, execute:

bash
codex mcp add point11 --url https://point11.ai/api/mcp
codex mcp login point11

Para usar uma chave de API, informe o nome da variável de ambiente que a contém:

bash
codex mcp add point11 --url https://point11.ai/api/mcp --bearer-token-env-var POINT11_API_KEY

Os clientes de desktop, CLI e IDE compartilham a configuração no seu computador. Consulte o guia de MCP da OpenAI.

Veja seu painel no seu assistente#

Peça uma visualização do painel do Discovery, como Participação da marca, Taxa de vitória da marca ou Concorrentes. Um assistente que mostra aplicativos interativos exibe o mesmo cartão que você vê no seu painel, com um link para abri-lo no Point11. Outros assistentes recebem um breve resumo dos mesmos números e o link.

Entre com sua conta ou use uma chave de API#

  • Entre com sua própria conta. O Point11 pede que você aprove o acesso e, depois, seu assistente ou ferramenta age com a sua função em cada organização da qual você faz parte. Use essa opção para assistentes de IA e para o seu próprio trabalho.
  • Use uma chave de API para software que funciona sem você, como um script ou uma tarefa agendada. Uma chave age por uma organização e só pode usar o acesso que você concede a ela.

Algumas coisas sempre precisam de você. Suas próprias conversas e projetos do Alpha, os comentários e os rascunhos de estudos do Research pertencem a uma pessoa, então uma chave de API não consegue acessá-los. Pausar ou excluir uma campanha, convidar alguém ou remover um membro pede sua aprovação primeiro. Você vê a organização e exatamente o que vai mudar, e sua aprovação vale apenas para essa solicitação. Faturamento, chaves de API e funções de membros só mudam no painel.

O trabalho que você inicia pelo servidor MCP, pela API ou pela CLI conta para o seu plano da mesma forma que no painel.

Escolha o que cada assistente pode fazer#

Todo assistente de IA ou aplicativo que já agiu em seu nome aparece em Configurações > Segurança, em Aplicativos conectados. Escolha o que cada um pode fazer naquela organização: Total, Somente leitura ou Bloqueado. Proprietários e administradores também escolhem o que os assistentes dos membros podem fazer em toda a organização, em Configurações > Segurança > Organização, em Clientes de IA (MCP): Permitido, Somente leitura ou Desativado, e revogam o aplicativo de um membro em Aplicativos conectados dos membros. Uma alteração vale a partir da próxima solicitação, e as chaves de API não são afetadas.

Crie uma chave de API#

Administradores e proprietários podem criar chaves.

  1. Abra Configurações > Chaves de API e selecione Criar chave.
  2. Informe um Nome e escolha o Acesso da chave em cada produto, quando ela Expira e a quem ela Pertence.
  3. Selecione Criar e copie a chave. Você só a vê uma vez.

Guarde a chave em um gerenciador de segredos, nunca no seu código. Uma organização pode ter até 10 chaves ativas. Para desativar uma chave, selecione Revogar; Rotacionar dá a ela um novo segredo. Uma chave que pertence a Mim é revogada quando você sai da organização ou deixa de poder gerenciar chaves; uma que pertence à Organização continua funcionando.

Faça sua primeira solicitação#

Envie sua chave como um token bearer:

bash
curl https://point11.ai/api/v1/discovery/campaigns \
  -H "Authorization: Bearer $POINT11_API_KEY"

As solicitações de leitura usam GET. As solicitações que alteram algo usam POST com um corpo JSON e um cabeçalho Idempotency-Key com um novo UUID:

bash
curl https://point11.ai/api/v1/inspector/scans/start \
  -H "Authorization: Bearer $POINT11_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com"}'

Se você entrar com sua conta em vez de usar uma chave, envie também Point11-Organization com o ID da sua organização. Copie-o em Configurações > Chaves de API.

Trate as respostas#

  • Novas tentativas. Para repetir uma solicitação com segurança, envie-a novamente com o mesmo Idempotency-Key. Repetir uma criação ou um início devolve a primeira resposta, e nada é executado duas vezes. Qualquer outra alteração repetida é executada de novo e responde com o estado em que deixou as coisas, então uma exclusão repetida que responde 404 significa que o item já não existe. Use uma nova chave para cada nova solicitação. Pelo servidor MCP, seu assistente envia a chave como idempotencyKey. Ela é obrigatória para criar ou iniciar algo; para qualquer outra alteração, é opcional, e uma solicitação sem ela é executada como uma nova solicitação.
  • Listas. Informe limit, até 100. Para obter a próxima página, passe o nextCursor da resposta anterior como cursor. nextCursor é null na última página.
  • Trabalhos mais longos. Iniciar uma análise ou uma campanha responde 202 na hora, com um runId. Acompanhe o progresso com GET /api/v1/platform/runs-v2/{runId} ou com platform_runs_get_v2 no servidor MCP.
  • Erros. Todo erro tem um code, uma message e um request_id. Decida o que fazer com base no code e inclua o request_id quando pedir ajuda.
  • Limites. Cada chave tem uma cota de solicitações, assim como cada pessoa que entra com a própria conta, somando todas as organizações e assistentes que ela usa. Os cabeçalhos RateLimit-Remaining e RateLimit-Reset mostram quanto resta. Quando a cota acaba, você recebe 429; aguarde os segundos indicados em Retry-After e tente novamente.

Use a CLI#

A CLI é o Restish, que lê a referência da API e transforma cada solicitação em um comando com o nome dela, como discovery-campaigns-list. Ela usa uma chave de API. Instale o Restish, por exemplo com brew install restish, coloque sua chave em POINT11_API_KEY e conecte o Restish ao Point11:

bash
restish api connect p11 https://point11.ai --no-discover
restish api set p11 'profiles.default.auth: {type: bearer, params: {token: env:POINT11_API_KEY}}'
restish api set p11 'profiles.default.credentials.apiKey.auth: {type: bearer, params: {token: env:POINT11_API_KEY}}'
restish api sync p11

Depois, execute qualquer solicitação pelo nome do comando:

bash
restish p11 discovery-campaigns-list

Para uma solicitação que altera algo, coloque o Idempotency-Key primeiro:

bash
restish p11 inspector-scans-start "$(uuidgen)" url: https://example.com

Execute restish api sync p11 novamente para receber novas solicitações.