Referência de endpoints da API REST
Cada endpoint é uma requisição GET em https://app.searcherries.com/api/v1 com um token Bearer. Leia a visão geral para saber sobre autenticação, períodos, paginação, limites de requisições e erros. O documento OpenAPI em https://app.searcherries.com/openapi/v1.yaml descreve os mesmos endpoints para clientes de API.
Cada endpoint retorna o conjunto de dados da ferramenta MCP indicada ao lado, então uma análise escrita para uma das duas interfaces vale para a outra.
| Endpoint | Ferramenta MCP | Retorna |
|---|---|---|
GET /projects | list-projects | Os seus projetos com status, plataformas, fontes conectadas e contagens de dados. |
GET /projects/{project} | get-project-summary | Um snapshot compacto de um projeto. |
GET /projects/{project}/answers | get-ai-answers | Respostas de IA armazenadas com as respectivas avaliações. |
GET /projects/{project}/search-performance | get-search-performance | Dados do Google Search Console ou do Bing de uma janela. |
GET /projects/{project}/competitors | get-competitors | Marcas que as plataformas de IA mencionam, em ranking, em detalhe ou por mês. |
GET /projects/{project}/citations | get-citations | URLs ou domínios citados. |
GET /projects/{project}/ai-traffic | get-ai-traffic | Tráfego do GA4 vindo de assistentes de IA e de AI Overviews. |
GET /projects/{project}/action-plan | get-action-plan | Próximos passos priorizados, com evidências. |
{project} é o id numérico do projeto que GET /projects retorna. Um id que pertence a outra conta responde 404.
GET /projects
Lista os projetos da sua conta. Não aceita parâmetros.
Cada projeto traz id, brand_name, brand_website, status, country, language, selected_ai_models, last_checked_at, connections (se GA4, Search Console e Bing estão conectados), connected_data (o quão recente é o snapshot mais novo armazenado de cada fonte) e data_availability (contagens de perguntas, respostas, avaliações, snapshots de concorrentes e snapshots de fontes conectadas armazenados).
GET /projects/{project}
Um snapshot compacto de um projeto, com cerca de 16 KB. Blocos: profile (marca, mercado, perfil do negócio), questions (a pergunta principal e até 15 perguntas adicionais com a última e a próxima verificação), ai_visibility (pontuação, menções por plataforma, variação em relação ao período anterior, share of voice), answer_insights (com que frequência e com que destaque a marca é mencionada, respostas negativas e fora do tema), competitors (a própria marca e o top 10), citations (domínios mais citados), search (totais de 30 dias do Google e do Bing com listas top 5), ai_traffic (tráfego de IA do GA4 em 30 dias), connections (estado das conexões) e recommendations (resumo mais recente).
| Parâmetro | Significado |
|---|---|
period | Período de visibilidade em IA. Padrão last_30_days. |
include | Blocos a incluir, separados por vírgula. Omita para receber o resumo completo. |
A resposta repete em included os blocos que contém e traz o link do relatório do projeto em report_url.
GET /projects/{project}/answers
Respostas de IA armazenadas, uma linha por verificação e plataforma, junto com as avaliações: prominence_level (0 não mencionada, 1 mencionada de passagem, 2 uma das opções, 3 principal recomendação), on_topic, names_brands, brand_sentiment, brand_drawback, evidence_quote, URLs citadas e as buscas na web que a plataforma fez. brand_mentioned é null nas respostas que a avaliação noturna ainda não processou.
| Parâmetro | Significado |
|---|---|
period | Período do relatório; ignorado quando since ou until é informado. |
since, until | Datas de verificação, YYYY-MM-DD. |
prompt_id | Uma das perguntas dos clientes (o id dela no resumo do projeto). |
platform | Uma plataforma de IA: chatgpt, perplexity, ai_overviews, gemini, claude ou grok. |
prominence_max | Mantém as respostas com destaque até este nível. 1 lista as lacunas. |
only_flagged | Só respostas fora do tema, e respostas negativas ou que apontam uma desvantagem quando uma frase da resposta comprova isso (evidence_quote). |
include_answer_text | Inclui o texto da resposta. Limita a página a 20 linhas. |
max_answer_chars | Caracteres por resposta quando o texto é incluído (de 200 a 20000, padrão 1200). |
limit, offset | Paginação, de 1 a 100 linhas. |
Um prompt_id de outro projeto gera um 422 em prompt_id.
GET /projects/{project}/search-performance
Dados do Google Search Console ou do Bing Webmaster Tools de uma janela.
| Parâmetro | Significado |
|---|---|
source | google (padrão) ou bing. |
period | 30d (padrão), 90d, 365d. |
dataset | summary (padrão), top_queries, top_pages, top_countries, queries_by_country, opportunities, trends, ai_question_queries (só Google), daily, history. |
query_contains, page_contains, country | Filtros de texto nos conjuntos de dados em lista. |
min_impressions, min_clicks, min_position, max_position | Filtros numéricos. |
sort | clicks (padrão), impressions, ctr, position. |
limit, offset | Paginação dos conjuntos de dados em lista. |
As listas trazem apenas a amostra armazenada dos principais itens (até 50 linhas por dimensão e até 1.000 consultas em forma de pergunta) e não incluem todas as linhas. history soma a série diária por mês do calendário.
GET /projects/{project}/competitors
| Parâmetro | Significado |
|---|---|
period | Período do relatório. |
dataset | ranking (padrão), detail, history. |
competitor | Nome da marca ou parte dele. Obrigatório para detail. |
include_highlights, highlights_per_platform | Frases de destaque por plataforma no ranking (padrão 3, máximo 5). |
limit, offset | Linhas para ranking (padrão 15, máximo 50) ou meses para history (padrão 12). |
ranking retorna uma linha por marca no período, incluindo a própria marca, ordenadas por visibilidade. history retorna os snapshots mensais armazenados.
GET /projects/{project}/citations
| Parâmetro | Significado |
|---|---|
period | Período do relatório. |
group_by | url (padrão) ou domain. |
platform, prompt_id, url_contains | Filtros para o agrupamento por URL. |
own_site_only | Só URLs do site do projeto. |
limit, offset | Paginação. |
GET /projects/{project}/ai-traffic
| Parâmetro | Significado |
|---|---|
period | 30d (padrão), 90d, 365d. |
dataset | summary (padrão), sources, landing_pages, daily, history. |
source | Uma fonte de IA: chatgpt, gemini, perplexity, claude, copilot, meta_ai, other_ai_assistants ou ai_overviews. |
path_contains | Filtro pelos caminhos das páginas de entrada. |
limit, offset | Paginação de landing_pages. |
GET /projects/{project}/action-plan
Próximos passos priorizados para um projeto.
| Parâmetro | Significado |
|---|---|
audience | business (padrão) para prioridades de tráfego e de negócio, marketing para respostas sobre a marca e conteúdo, seo para páginas e consultas de busca. |
period | Período de visibilidade em IA. Padrão last_30_days. Busca e tráfego usam os próprios snapshots móveis de 30 dias. |
limit | Número máximo de ações, de 1 a 10 (padrão 5). Quando há poucas evidências, a resposta traz menos ações. |
A resposta tem um status (ready, needs_data ou no_priority_signals), as actions, data_notes sobre fontes ausentes ou desatualizadas e um snapshot do projeto. Cada ação traz um título, um responsável sugerido, o próximo passo, evidências com data, uma medida de sucesso, um link para o relatório correspondente da Searcherries e next_request, a requisição à API que retorna as linhas que sustentam a ação.
As ações vêm de quatro sinais armazenados: respostas negativas sobre a marca ou que apontam uma desvantagem, respostas em que a marca não é mencionada, consultas do Search Console e do Bing com muitas impressões e poucos cliques, e as páginas de entrada dos visitantes vindos de IA. A ordem segue o público escolhido. O plano é uma sugestão montada com dados armazenados; ele não estima impacto, esforço nem receita.
Tamanho e atualidade dos dados
As respostas são documentos JSON únicos. O resumo do projeto fica em torno de 16 KB, o plano de ação em até cerca de 24 KB e os demais endpoints em até cerca de 40 KB com os limites padrão. Confira period, fetched_at e is_stale antes de combinar números de endpoints diferentes.