Mastheads

npx add-mcp 'https://api.mastheads.app/v1/mcp'

A maioria das chaves apenas lê. Uma chave criada com acesso total também pode iniciar trabalhos — um artigo, um lote, um relatório de pesquisa ou uma auditoria de domínio — e publicar um trabalho concluído, a partir do seu próprio código ou de um assistente de IA.

A permissão é fixada na criação

Quando você cria uma chave em Configurações → Conta → Acesso à API, escolhe Somente leitura, que é o padrão, ou Acesso total. Não há como alternar depois. Uma chave somente leitura permanece somente leitura por toda a sua vida, e para obter uma chave de gasto você cria uma nova — o banco de dados concede a permissão quando a linha é inserida e nunca em uma atualização, então isso não é uma regra que a interface está pedindo educadamente para você seguir.

Toda chave que existia antes da introdução do acesso total é uma chave somente leitura, e nada mudou sobre ela.

Ela age como a pessoa que a criou

Uma chave de acesso total não é uma conta separada com orçamento próprio. O trabalho que ela inicia é feito como seu proprietário, passando pelas mesmas proteções que o painel passa: o teto horário da redação, a cota do plano, a permissão dessa pessoa para gastar na redação, termos aceitos e uma conta aberta. Se essa pessoa não pudesse iniciar o trabalho no painel, a chave também não pode iniciá-lo.

Uma chave é carimbada com a redação em que seu proprietário estava quando foi criada. Se essa pessoa depois se mudar para outra redação, a chave para em vez de cobrar a nova: 403 wrong_newsroom. Crie uma nova chave lá.

20 ações pagas por hora, por chave

Além de tudo acima, cada chave de acesso total pode iniciar no máximo 20 ações pagas por hora. Um artigo, uma linha de um lote, um relatório e uma auditoria contam como um cada. A contagem é por chave, então uma segunda chave tem a sua própria, e uma chave somente leitura nunca gasta dela.

Exceder o limite é um 429 rate_limited com Retry-After: 60, e nada é iniciado. Um lote é cortado no espaço restante em vez de ser recusado inteiro — as linhas que cabem iniciam, e cada linha além do limite retorna em refused com sua posição e o motivo. Chaves vivem em scripts e vazam com mais frequência do que logins, então esse teto existe para transformar o raio de explosão de uma chave vazada em um número, em vez de uma cota.

O arquivo completo da conta é separado

Um arquivo contendo tudo que a conta possui é uma tarefa do painel, não da API: Configurações → Conta → Baixar tudo. Veja Limites de taxa e erros para o que /v1/exports responde.

As cinco portas

As quatro primeiras respondem 202 com um id e iniciam o trabalho em segundo plano. Publicar é a exceção e a mais pesada: ela responde quando a postagem está no ar, então não há nada para consultar.

Endpoint	Inicia
/v1/editions/{slug}/articles	Comissiona um artigo em um domínio. Responde 202 com um id de trabalho.
/v1/editions/{slug}/articles/batch	Até 100 artigos em um único domínio em uma única chamada, com um motivo de recusa por linha.
/v1/editions/{slug}/research	Comissiona um relatório de pesquisa em um domínio. Responde 202 com um id de relatório.
/v1/editions/{slug}/audit	Rastreia um domínio que você verificou e audita o que está lá. Responde 202 com um id de rastreamento.
/v1/editions/{slug}/articles/{article_id}/publish	Coloca um artigo concluído no ar no site conectado ao domínio.

Um trabalho de artigo é consultado em GET /v1/jobs/{job_id}. Um relatório e uma auditoria têm cada um seu próprio caminho, nomeado em suas páginas, porque nenhum deles é um trabalho de artigo. Esses dois caminhos carregam o resultado concluído além do progresso, e qualquer chave sua pode lê-los — um resultado que você já pagou é uma leitura, então não precisa de acesso total e não gasta nada.

MCP

As mesmas quatro ações estão disponíveis via MCP, então Claude Code, Cursor ou qualquer cliente MCP pode iniciar trabalho na sua redação. O servidor é HTTP streamable, e a credencial é ou uma chave de API que você já possui ou, para um cliente que faz login com OAuth, uma criada para você quando você conecta (abaixo).

https://api.mastheads.app/v1/mcp

O endereço e um bloco de configuração para colar estão no painel em Configurações → Desenvolvedor.

Ferramenta	O que ela inicia
write_article	Um artigo em um domínio, escrito com os Padrões de Artigo salvos do domínio. Aceita domain_id e input, e o mesmo id opcional.
write_articles	Até 100 de uma vez, cada um com os Padrões de Artigo salvos do domínio. Aceita domain_id e inputs, cada linha uma string ou um objeto com input e id.
run_research	Um relatório de pesquisa em um domínio. Aceita domain_id.
run_audit	Uma auditoria de domínio inteiro. Aceita domain_id.
publish_article	Coloca um artigo concluído no ar no site conectado ao domínio.

Todas as cinco aparecem apenas para uma chave de acesso total. Conecte com uma chave somente leitura e a lista de ferramentas é apenas as ferramentas de leitura, então um assistente não pode oferecer gastar algo que nunca recebeu. Elas passam pela mesma porta que os endpoints acima — as mesmas 20 por hora, a mesma cota, as mesmas recusas — e aceitam o mesmo id opcional, então um assistente que tenta novamente após um timeout não comissiona o trabalho duas vezes. Ler um relatório de pesquisa ou auditoria concluído está no lado de leitura, listado para toda chave.

Conectando um aplicativo

Qualquer cliente MCP pode usar a chave diretamente, como acima. Um cliente que suporta OAuth — Codex, Claude e qualquer cliente que suporte — pode fazer login em vez disso, que é o caminho melhor quando disponível: nada para colar, nenhuma chave no disco. Para Codex, um comando faz tanto a conexão quanto o login:

codex mcp add mastheads --url https://api.mastheads.app/v1/mcp

O mesmo endereço funciona com claude mcp add --transport http para Claude Code. Claude.ai, ChatGPT e Claude Desktop não têm campo para chave; aponte-os para o mesmo endereço e você faz login com seu login do Mastheads em vez de colar qualquer coisa. Veja Autenticação para as linhas completas de configuração.

Fazer login mostra uma tela de consentimento com uma única escolha — Permitir que este aplicativo gaste — que está desligada a menos que você a ligue, e nunca é pré-marcada. Deixe desligada e o aplicativo lê; ligue e ele pode iniciar trabalho e publicar, sob as mesmas 20 por hora e a mesma cota que qualquer outra chave. Como uma chave, essa escolha é fixada no momento em que você a permite.

Aplicativos conectados são listados no painel em Configurações → Desenvolvedor, cada um com Desconectar, que faz exatamente o que revogar uma chave faz e tem efeito na próxima solicitação. Eles são contados separadamente das três chaves que você cria manualmente.

Acesso ao plano

O acesso total está nos mesmos planos que o resto da API: Growth e Pro. Não há cobrança separada para ele — o trabalho que uma chave inicia é medido exatamente como o trabalho iniciado no painel, da mesma cota.