O servidor MCP chama mais atenção, mas por baixo dele há uma API REST simples, e tudo o que o assistente consegue fazer, um script também consegue. Este artigo percorre os endpoints na ordem em que você provavelmente vai precisar deles, com um comando curl para cada um. Se preferir falar com ela pelo Claude, comece pelo artigo de lançamento.
URL base e autenticação
Base URL: https://provedly.app/api/v1
Header: Authorization: Bearer provedly_…
A chave é uma chave de API da conta, criada em Settings, em API keys. Ela começa com provedly_, é mostrada uma única vez e pode ser revogada a qualquer momento. Escolha Read only para scripts que só geram relatórios, e Read and write para qualquer coisa que altere o estado. A diferença está explicada em escolhendo uma chave de API.
Para os exemplos, coloque a chave numa variável de ambiente para que ela fique fora do histórico do shell:
export PROVEDLY_KEY="provedly_your_key_here"
Chaves ficam em servidores e no seu próprio terminal. Nunca coloque uma em JavaScript do navegador.
Lendo a sua conta
Comece pelo endpoint da conta. Ele retorna o seu plano, os limites e o uso atual, que são o contexto para todo o resto.
curl https://provedly.app/api/v1/account \
-H "Authorization: Bearer $PROVEDLY_KEY"
Depois, o que há na conta:
curl https://provedly.app/api/v1/sites -H "Authorization: Bearer $PROVEDLY_KEY"
curl https://provedly.app/api/v1/widgets -H "Authorization: Bearer $PROVEDLY_KEY"
curl https://provedly.app/api/v1/bars -H "Authorization: Bearer $PROVEDLY_KEY"
Itens individuais ficam em /widgets/{id} e /bars/{id}. Widgets, barras e sites podem ser referenciados pelo id, que é um UUID, ou pelo token, o que você tiver à mão. Um script que já tem o token de um widget a partir do snippet de instalação não precisa buscar o UUID antes.
Estatísticas
curl "https://provedly.app/api/v1/stats?days=30" \
-H "Authorization: Bearer $PROVEDLY_KEY"
A resposta traz impressões, cliques, pedidos verificados e pedidos assistidos por prova social com a receita, para o número de dias que você pedir. Assistido por prova social significa que o comprador viu uma notificação antes de comprar, associado por visitante numa janela de 30 dias, a mesma definição usada pelo painel e explicada em medindo pedidos assistidos por prova social. Mude days para 7 para um relatório semanal.
Alterando widgets e barras
Tudo nesta seção precisa de uma chave de leitura e escrita. Pausar ou retomar um widget é um PATCH:
curl -X PATCH https://provedly.app/api/v1/widgets/WIDGET_ID \
-H "Authorization: Bearer $PROVEDLY_KEY" \
-H "Content-Type: application/json" \
-d '{"status": "paused"}'
Envie "active" para retomar. Retomar é onde os limites do plano aparecem: se o plano permite um número fixo de widgets ativos e você já está nele, a requisição é recusada com um motivo em vez de passar do limite em silêncio. Uma chave somente leitura é recusada em qualquer escrita, seja qual for o corpo.
Criar uma barra é um POST para /bars. Mantenha o corpo num arquivo para que seja fácil revisar:
curl -X POST https://provedly.app/api/v1/bars \
-H "Authorization: Bearer $PROVEDLY_KEY" \
-H "Content-Type: application/json" \
-d @winter-launch.json
Uma barra nova criada pela API começa pausada. Isso é proposital: ninguém a vê até você conferi-la, e um erro de digitação num script não consegue colocar uma barra pela metade na frente dos visitantes. Ir ao ar é uma segunda chamada:
curl -X PATCH https://provedly.app/api/v1/bars/BAR_ID \
-H "Authorization: Bearer $PROVEDLY_KEY" \
-H "Content-Type: application/json" \
-d '{"status": "active"}'
A ativação respeita o limite de barras do seu plano do mesmo jeito que a retomada de widgets.
O mesmo endpoint PATCH edita o nome, a mensagem e a data de término de uma barra, e a pausa ou retoma. Para datas de término, ends_at aceita um horário local como "2026-12-01 09:00", lido no fuso horário da própria barra, ou um timestamp ISO 8601 completo:
curl -X PATCH https://provedly.app/api/v1/bars/BAR_ID \
-H "Authorization: Bearer $PROVEDLY_KEY" \
-H "Content-Type: application/json" \
-d '{"ends_at": "2026-12-01 09:00"}'
A forma local costuma ser o que você quer num lançamento, porque "9h" significa 9h onde a barra está configurada, não onde o seu servidor por acaso roda. Mais sobre datas em agendando contagens regressivas de lançamento.
Adicionando registros
A Records API, POST /widgets/{token}/records, não mudou de formato e agora também aceita uma chave da conta, então uma chave pode alimentar todos os widgets da conta em vez de manter uma chave de widget separada para cada um. Os campos e as regras de idempotência estão na referência da Records API, e a versão com chave de conta é explicada em enviando registros com uma chave de conta.
Registros criados assim mantêm a origem API e aparecem no widget com o rótulo visível "Imported", sem a marca Verified. A API não tem nenhum campo que marque um registro como verificado, e nenhum nível de chave acrescenta um. Só webhooks assinados do Stripe, Shopify e WooCommerce geram registros verificados.
Entendendo as recusas
A maioria das falhas se encaixa em poucos grupos:
| Situação | O que você recebe |
|---|---|
| Chave ausente, errada ou revogada | Um erro de autenticação |
| Chave somente leitura num endpoint de escrita | Uma recusa dizendo que a chave é somente leitura |
| Mudança ultrapassaria um limite do plano | Uma recusa citando o limite |
| Campo inválido, como uma data errada | Um erro de validação daquele campo |
Scripts devem tratar recusas por limite de plano como informação para uma pessoa, não como algo a tentar de novo.
Perguntas frequentes
A API é a mesma coisa que o servidor MCP usa?
As ferramentas MCP cobrem as mesmas ações com as mesmas regras: mesmas chaves, mesmos limites de plano, mesma recusa em verificar registros. Use a que for melhor para cada tarefa.
Posso criar uma barra que vai ao ar na hora?
Não numa única chamada. Barras criadas pela API começam pausadas, e você as ativa com uma segunda requisição. É uma linha a mais no script, e evita surpresas.
Quais planos incluem a API?
Todos, inclusive o Free. Os limites de widgets, barras e impressões de cada plano valem normalmente.
Veja o que cada plano permite na página de preços.