Referencia de endpoints de la API REST
Cada endpoint es una petición GET bajo https://app.searcherries.com/api/v1 con un token bearer. Lee la introducción para la autenticación, los periodos, la paginación, los límites de peticiones y los errores. El documento OpenAPI en https://app.searcherries.com/openapi/v1.yaml describe los mismos endpoints para clientes de API.
Cada endpoint devuelve el conjunto de datos de la herramienta MCP indicada a su lado, así que un análisis escrito contra una de las dos superficies sirve para la otra.
| Endpoint | Herramienta MCP | Devuelve |
|---|---|---|
GET /projects | list-projects | Tus proyectos con estado, plataformas, fuentes conectadas y recuentos de datos. |
GET /projects/{project} | get-project-summary | Una instantánea compacta de un proyecto. |
GET /projects/{project}/answers | get-ai-answers | Respuestas de IA almacenadas con sus valoraciones. |
GET /projects/{project}/search-performance | get-search-performance | Datos de Google Search Console o Bing de una ventana. |
GET /projects/{project}/competitors | get-competitors | Marcas que nombran las plataformas de IA, en ranking, en detalle o por mes. |
GET /projects/{project}/citations | get-citations | URL o dominios citados. |
GET /projects/{project}/ai-traffic | get-ai-traffic | Tráfico de GA4 procedente de asistentes de IA y AI Overviews. |
GET /projects/{project}/action-plan | get-action-plan | Próximos pasos priorizados con evidencia. |
{project} es el id numérico del proyecto que devuelve GET /projects. Un id que pertenece a otra cuenta responde 404.
GET /projects
Lista los proyectos de tu cuenta. No admite parámetros.
Cada proyecto incluye id, brand_name, brand_website, status, country, language, selected_ai_models, last_checked_at, connections (si GA4, Search Console y Bing están conectados), connected_data (frescura de la instantánea más reciente almacenada por fuente) y data_availability (recuentos de preguntas, respuestas, valoraciones, instantáneas de competidores e instantáneas de fuentes conectadas almacenadas).
GET /projects/{project}
Una instantánea compacta de un proyecto, de unos 16 KB. Bloques: profile (marca, mercado, perfil del negocio), questions (la pregunta principal y hasta 15 preguntas adicionales con su última y próxima comprobación), ai_visibility (puntuación, menciones por plataforma, cambio frente al periodo anterior, cuota de voz), answer_insights (con qué frecuencia y protagonismo se nombra la marca, respuestas negativas y fuera de tema), competitors (marca propia y top 10), citations (dominios más citados), search (totales de 30 días de Google y Bing con listas top 5), ai_traffic (tráfico de IA de GA4 de 30 días), connections (estado) y recommendations (último resumen).
| Parámetro | Significado |
|---|---|
period | Periodo de visibilidad en IA. Predeterminado last_30_days. |
include | Bloques a incluir, separados por comas. Omítelo para el resumen completo. |
La respuesta repite en included los bloques que contiene y enlaza el informe del proyecto en report_url.
GET /projects/{project}/answers
Respuestas de IA almacenadas, una fila por comprobación y plataforma, unidas a sus valoraciones: prominence_level (0 no nombrada, 1 nombrada de pasada, 2 una de las opciones, 3 recomendación principal), on_topic, names_brands, brand_sentiment, brand_drawback, evidence_quote, URL citadas y las búsquedas web que hizo la plataforma. brand_mentioned es null en las respuestas a las que la valoración nocturna todavía no ha llegado.
| Parámetro | Significado |
|---|---|
period | Periodo del informe; se ignora cuando se indica since o until. |
since, until | Fechas de comprobación, YYYY-MM-DD. |
prompt_id | Una pregunta de cliente (su id en el resumen del proyecto). |
platform | Una plataforma de IA: chatgpt, perplexity, ai_overviews, gemini, claude o grok. |
prominence_max | Conserva las respuestas con un protagonismo como máximo de este nivel. 1 lista los huecos. |
only_flagged | Solo respuestas negativas, con inconvenientes o fuera de tema. |
include_answer_text | Incluye el texto de la respuesta. Limita la página a 20 filas. |
max_answer_chars | Caracteres por respuesta cuando se incluye el texto (de 200 a 20000, predeterminado 1200). |
limit, offset | Paginación, de 1 a 100 filas. |
Un prompt_id de otro proyecto es un 422 en prompt_id.
GET /projects/{project}/search-performance
Datos de Google Search Console o Bing Webmaster Tools de una ventana.
| Parámetro | Significado |
|---|---|
source | google (predeterminado) o bing. |
period | 30d (predeterminado), 90d, 365d. |
dataset | summary (predeterminado), top_queries, top_pages, top_countries, queries_by_country, opportunities, trends, ai_question_queries (solo Google), daily, history. |
query_contains, page_contains, country | Filtros de texto en los conjuntos de datos de lista. |
min_impressions, min_clicks, min_position, max_position | Filtros numéricos. |
sort | clicks (predeterminado), impressions, ctr, position. |
limit, offset | Paginación de los conjuntos de datos de lista. |
Las listas son la muestra principal almacenada (hasta 50 filas por dimensión, hasta 1000 consultas con forma de pregunta), no una exportación exhaustiva. history suma la serie diaria por mes natural.
GET /projects/{project}/competitors
| Parámetro | Significado |
|---|---|
period | Periodo del informe. |
dataset | ranking (predeterminado), detail, history. |
competitor | Nombre de la marca o un fragmento. Obligatorio para detail. |
include_highlights, highlights_per_platform | Frases destacadas por plataforma en el ranking (predeterminado 3, máximo 5). |
limit, offset | Filas para ranking (predeterminado 15, máximo 50) o meses para history (predeterminado 12). |
ranking devuelve una fila por marca para el periodo, incluida la marca propia, ordenadas por visibilidad. history devuelve las instantáneas mensuales almacenadas.
GET /projects/{project}/citations
| Parámetro | Significado |
|---|---|
period | Periodo del informe. |
group_by | url (predeterminado) o domain. |
platform, prompt_id, url_contains | Filtros para la agrupación por URL. |
own_site_only | Solo URL del sitio web del proyecto. |
limit, offset | Paginación. |
GET /projects/{project}/ai-traffic
| Parámetro | Significado |
|---|---|
period | 30d (predeterminado), 90d, 365d. |
dataset | summary (predeterminado), sources, landing_pages, daily, history. |
source | Una fuente de IA: chatgpt, gemini, perplexity, claude, copilot, meta_ai, other_ai_assistants o ai_overviews. |
path_contains | Filtro sobre las rutas de las páginas de entrada. |
limit, offset | Paginación para landing_pages. |
GET /projects/{project}/action-plan
Próximos pasos priorizados para un proyecto.
| Parámetro | Significado |
|---|---|
audience | business (predeterminado) para prioridades de tráfico y negocio, marketing para respuestas de marca y contenido, seo para páginas y consultas de búsqueda. |
period | Periodo de visibilidad en IA. Predeterminado last_30_days. Búsqueda y tráfico usan sus propias instantáneas móviles de 30 días. |
limit | Número máximo de acciones, de 1 a 10 (predeterminado 5). Se devuelven menos cuando la evidencia es escasa. |
La respuesta tiene un status (ready, needs_data o no_priority_signals), las actions, data_notes sobre fuentes ausentes u obsoletas y un snapshot del proyecto. Cada acción incluye un título, un responsable sugerido, el siguiente paso, evidencia con fecha, una medida de éxito, un enlace al informe correspondiente de Searcherries y next_request, la petición a la API que devuelve las filas que la respaldan.
Las acciones salen de cuatro señales almacenadas: respuestas negativas sobre la marca o que nombran un inconveniente, respuestas donde la marca no se nombra, consultas de Search Console y Bing con muchas impresiones y pocos clics, y las páginas de entrada de los visitantes procedentes de IA. El orden sigue la audiencia elegida. El plan es una sugerencia construida con datos almacenados; no estima impacto, esfuerzo ni ingresos.
Tamaño y frescura
Las respuestas son documentos JSON únicos. El resumen del proyecto se mantiene en torno a 16 KB, el plan de acción en unos 24 KB y el resto de endpoints en unos 40 KB con los límites predeterminados. Comprueba period, fetched_at e is_stale antes de combinar cifras de endpoints distintos.