Proyectos

Un proyecto es una marca monitorizada: su dominio, configuración regional, prompts y competidores. Casi todos los demás endpoints reciben un project_id, así que empieza aquí.

GET/dimensions/projects

Lista los proyectos del usuario autenticado (también sirve como comprobación de autenticación). Los proyectos de pitch, instantáneas puntuales que se eliminan 90 días después de crearse, quedan fuera salvo que se use pitch=include o pitch=only.

GET/dimensions/projects/:id

Obtén información detallada sobre un proyecto: nombres coincidentes, dominios propios adicionales, sector, modelo de negocio, recuento de prompts por enfoque de marca, el límite de prompts propio del proyecto (prompt_limit, null si no tiene ninguno) con stats.prompts_available (cuántos prompts se pueden añadir todavía: el menor valor entre lo que le falta al proyecto para llegar a ese límite y los prompts que le quedan a la cuenta, null si no se aplica ninguno de los dos) y data_coverage (los modelos, países e idiomas que realmente tienen datos), de modo que una sola llamada sustituye a las consultas independientes de modelos y locales.

GET/dimensions/models

Lista los modelos presentes en las métricas diarias del proyecto.

GET/dimensions/locales

Lista los países e idiomas presentes en las métricas diarias del proyecto.

POST/projects

Crea un proyecto completo en una sola llamada (modo rápido): proyecto, prompts (en cola para ejecución y categorización), competidores y suscripción al correo semanal. Idempotente cuando se proporciona external_identifier. El proyecto siempre pertenece al propietario de la cuenta.

  • Cuerpo (JSON): website_url (obligatorio, URL HTTP(S) pública con un nombre de host DNS o una dirección IP pública; se rechazan las URL con credenciales, las direcciones IP privadas y especiales, localhost y los nombres de host internos), name (obligatorio), main_country (obligatorio), main_language (obligatorio), brand_name, description, industry (una clave o un array; una clave desconocida se rechaza y se indican las claves válidas), business_model, target_audience, brand_voice, goals, primary_products (array), matching_names (array), prompts (array, máx. 100), collections (array de objetos {name, prompts}, máx. 50; cada uno etiqueta prompts de la misma solicitud por su texto exacto), competitors (array de objetos {domain, brand_name, matching_names}), owned_media (objeto, Growth+), use_subdomain, weekly_email_subscribed, external_identifier (solo cuentas con embed habilitado; clave de idempotencia, [a-z0-9_-]{1,64}), execute_prompts_immediately (por defecto, true), pitch (por defecto, false; true crea un proyecto de pitch, una instantánea puntual para un cliente potencial que se ejecuta una sola vez, no ocupa ningún hueco de proyecto y se elimina a los 90 días salvo que se convierta; usa uno de los proyectos de pitch del mes y admite de 1 a 100 prompts).

PATCH/projects/:id

Actualiza el perfil del proyecto (el Brand Book y el emparejamiento de marca), con los mismos campos que en Configuración del proyecto, y también los dominios propios adicionales y el límite de prompts del proyecto. Los siete campos del Brand Book (industry, business_model, description, primary_products, target_audience, brand_voice, goals) se usan en todas las tareas de GEO Writer y en las sugerencias de prompts. industry, description y target_audience también ayudan a ajustar los consejos de Recomendaciones. Cambiar matching_names vuelve a ejecutar el emparejamiento de menciones y citaciones en todo el historial del proyecto en segundo plano, y cambiar additional_owned_domains reprocesa las respuestas anteriores que citan un dominio añadido o quitado (rematching: true; mientras tanto, las ediciones quedan bloqueadas); un cambio de brand_name solo se aplica a ejecuciones futuras. Solo el propietario de la cuenta puede cambiar additional_owned_domains. prompt_limit funciona como en Configuración de la cuenta > Límites de prompts (un límite más bajo no elimina ningún prompt), y una solicitud que solo envía este campo se guarda aunque haya un recálculo en curso. pitch: false, enviado por sí solo, convierte un proyecto de pitch en un proyecto monitorizado: conserva sus datos, ocupa un hueco de proyecto, sus prompts se ejecutan según la programación de la cuenta y no se puede deshacer. Se rechazan los campos desconocidos y cada solicitud se aplica completa o no se aplica en absoluto.

  • Cuerpo (JSON): envía solo los campos que quieras cambiar: name (una etiqueta; no cambia la detección de menciones salvo que brand_name esté vacío), brand_name, description, industry (una sola clave, o un array que se guarda como array), business_model, target_audience, brand_voice, goals, primary_products (array de sustitución completa), matching_names (array de SUSTITUCIÓN COMPLETA; envía todas las variantes que quieras conservar), additional_owned_domains (array de SUSTITUCIÓN COMPLETA de hasta 10 dominios; cada uno debe ser el dominio propio de un sitio web, así que se rechazan los subdominios y las plataformas compartidas por muchas empresas; [] vacía la lista; solo puede enviarlo el propietario de la cuenta), prompt_limit (el número máximo de prompts que puede tener el proyecto, como en Configuración de la cuenta > Límites de prompts: un número entero de 1 a 2147483647, o null para quitar el límite; solo puede enviarlo el propietario de la cuenta o un administrador de la cuenta (copropietario) con permiso de actualización en Proyectos; una clave limitada a algunos proyectos recibe ERR_KEY_PROJECT_SCOPED).

DELETE/projects/:id

Elimina un proyecto, igual que el botón «Eliminar proyecto» de Configuración del proyecto. No se puede deshacer: el proyecto desaparece de inmediato y libera un hueco de proyecto, y después un trabajo en segundo plano elimina sus prompts, respuestas, menciones, citaciones, datos de sentimiento, competidores e historial de métricas. El proyecto se quita de las claves de API limitadas a él, y una clave que se queda sin ningún proyecto se revoca. Un miembro del equipo necesita permiso para eliminar proyectos.

Ruta:
  • :idid del proyecto

Devuelve ERR_PROJECT_NOT_FOUND para un proyecto que la clave no pueda ver o que ya se esté eliminando. Requiere una clave con el ámbito read_write que no esté limitada a algunos proyectos (de lo contrario, devuelve ERR_KEY_PROJECT_SCOPED).

Asistente de borradores de proyecto

Asistente de creación de proyectos en varios pasos con sugerencias de IA: POST /project_drafts inicia un borrador (devuelve el nombre, la descripción y el sector sugeridos para la URL), PATCH envía cada paso (details, prompts, competitors, owned_media) con una validación estricta del avance entre pasos y devuelve sugerencias para el siguiente paso, y POST /project_drafts/:id/finalize crea el proyecto real. Los borradores caducan tras 24h.

  • La website_url inicial debe ser una URL HTTP(S) pública con un nombre de host DNS o una dirección IP pública. Se rechazan las URL con credenciales, las direcciones IP privadas y especiales, localhost y los nombres de host internos. Pasos: details (name obligatorio), prompts (máx. 100, sujeto a cuota), competitors (limitado por plan), owned_media (opcional, Growth+). Sugerencias por paso, con opción de desactivarlas mediante suggest=false; las URL frías pueden tardar hasta ~2 minutos, configura el timeout del cliente en 180s. Finalize es idempotente y vuelve a comprobar todos los requisitos.