Campañas GTM

Las campañas GTM son los objetos de campaña de AI-Studio de graph8: un brief, una secuencia (referencias ordenadas de pasos) y un catálogo de pasos (las definiciones reales de cada paso). Cada campaña gestiona un conjunto de documentos generados (brief de campaña, documento de secuencia, copy de anuncios, copy de landing page, etc.).

Estos endpoints son la variante de alcance organizacional que utilizan Studio, MCP y el modo GTM de Claude Desktop. La misma superficie también se expone en /repos/{repo_id}/campaigns para usuarios de CLI con spine instalado; consulte la referencia de la CLI para esa variante.

Endpoint	Método	Descripción
`/campaigns`	GET	Listar campañas
`/campaigns`	POST	Crear una campaña
`/campaigns/ideas`	GET	Listar ideas de campaña guardadas
`/campaigns/{id}`	GET	Obtener una campaña con sus documentos
`/campaigns/{id}`	PATCH	Actualizar campos de contenido de la campaña
`/campaigns/{id}/documents`	GET	Listar documentos de una campaña
`/campaigns/{id}/documents`	POST	Crear un documento
`/campaigns/{id}/documents/{doc_id}`	GET	Obtener el contenido completo del documento
`/campaigns/{id}/documents/{doc_id}`	PUT	Actualizar el contenido del documento
`/campaigns/{id}/documents/{doc_id}`	DELETE	Eliminar un documento
`/campaigns/{id}/sequence`	GET	Obtener documentos de secuencia y catálogo de pasos
`/campaigns/{id}/sequence`	PUT	Reemplazar el orden de los pasos de la secuencia
`/campaigns/{id}/sequence/steps`	POST	Agregar un paso
`/campaigns/{id}/sequence/steps/{step_id}`	PUT	Actualizar la definición de un paso
`/campaigns/{id}/sequence/steps/{step_id}`	DELETE	Eliminar un paso
`/campaigns/{id}/launch`	POST	Poner en cola el lanzamiento de la campaña

Para esquemas legibles por máquina, consulte la documentación interactiva de la API.

Listar campañas

GET /campaigns

Devuelve todas las campañas no archivadas de la organización, paginadas.

Parámetros de consulta

Parámetro	Tipo	Predeterminado	Descripción
`page`	integer	1	Número de página
`limit`	integer	50	1-200

Ejemplo

cURL

curl "https://be.graph8.com/api/v1/campaigns?limit=10" \
  -H "Authorization: Bearer $API_KEY"

Respuesta

{
  "data": [
    {
      "id": "cmp_abc",
      "name": "Q2 Outbound - VP Marketing",
      "slug": "q2-outbound-vp-marketing",
      "status": "draft",
      "category": "Outbound",
      "goal": "Book discovery calls",
      "target_persona": "VP Marketing at mid-market SaaS",
      "created_at": "2026-04-01T10:00:00Z"
    }
  ]
}

Crear campaña

POST /campaigns

Crea una nueva campaña. El slug se genera automáticamente a partir de name.

Cuerpo de la solicitud

Campo	Tipo	Requerido	Descripción
`name`	string	Sí	Nombre de la campaña
`category`	string	No (predeterminado `Outbound`)	Categoría de la campaña
`brief`	string	No	Brief de la campaña
`core_concept`	string	No	Concepto en una línea
`primary_hook`	string	No	Texto del gancho principal
`target_persona`	string	No	Persona objetivo
`goal`	string	No	Objetivo de la campaña

Ejemplo

cURL

curl -X POST "https://be.graph8.com/api/v1/campaigns" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Q2 Outbound - VP Marketing",
    "category": "Outbound",
    "primary_hook": "Cut SDR ramp time in half",
    "goal": "Book discovery calls"
  }'

Respuesta

{
  "data": {
    "id": "cmp_abc",
    "name": "Q2 Outbound - VP Marketing",
    "slug": "q2-outbound-vp-marketing",
    "status": "draft",
    "category": "Outbound"
  }
}

Listar ideas de campaña

GET /campaigns/ideas

Devuelve las ideas de campaña guardadas o generadas con IA (antes de su conversión). Utilícelas para inicializar POST /campaigns.

Parámetros de consulta

Parámetro	Tipo	Predeterminado	Descripción
`favorited`	boolean	-	Filtrar solo las ideas marcadas como favoritas
`limit`	integer	50	1-200

Respuesta

{
  "data": [
    {
      "id": "idea_001",
      "rank": 1,
      "campaign_name": "Sales Velocity Diagnostic",
      "campaign_category": "Outbound",
      "campaign_focus": "Mid-market RevOps",
      "core_concept": "...",
      "why_this_works": "...",
      "primary_hook": "Find your stuck deals in 5 minutes",
      "secondary_hooks": ["..."],
      "target_channels": ["email", "linkedin"],
      "required_assets": ["landing page", "demo video"],
      "execution_complexity": "medium",
      "expected_impact": "high",
      "proof_points": ["..."],
      "framework_inspiration": "Challenger",
      "source": "studio_generated",
      "favorited": true,
      "converted_to_campaign": false,
      "converted_campaign_id": null,
      "created_at": "2026-04-01T10:00:00Z",
      "updated_at": "2026-04-01T10:00:00Z"
    }
  ]
}

Obtener campaña

GET /campaigns/{campaign_id}

Devuelve los detalles de la campaña junto con un resumen de los documentos completados.

Ejemplo

cURL

curl "https://be.graph8.com/api/v1/campaigns/cmp_abc" \
  -H "Authorization: Bearer $API_KEY"

Respuesta

{
  "data": {
    "id": "cmp_abc",
    "name": "Q2 Outbound - VP Marketing",
    "slug": "q2-outbound-vp-marketing",
    "status": "draft",
    "category": "Outbound",
    "goal": "Book discovery calls",
    "target_persona": "VP Marketing at mid-market SaaS",
    "brief": "...",
    "core_concept": "...",
    "primary_hook": "Cut SDR ramp time in half",
    "channels": ["email", "linkedin"],
    "documents": [
      {"id": "doc_001", "name": "Campaign Brief", "type": "campaign_brief"},
      {"id": "doc_002", "name": "Sequence", "type": "sequence"}
    ],
    "created_at": "2026-04-01T10:00:00Z",
    "updated_at": "2026-04-10T14:30:00Z"
  }
}

Errores

Estado	Significado
`404`	Campaña no encontrada

Actualizar campaña

PATCH /campaigns/{campaign_id}

Actualiza los campos de contenido de una campaña.

Cuerpo de la solicitud

Campo	Tipo	Descripción
`name`	string	Nombre de la campaña
`brief`	string	Brief de la campaña
`core_concept`	string	Concepto central
`primary_hook`	string	Texto del gancho principal
`target_persona`	string	Persona objetivo
`category`	string	Categoría de la campaña
`goal`	string	Objetivo de la campaña

Errores

Estado	Significado
`400`	No se proporcionaron campos
`404`	Campaña no encontrada

Listar documentos de la campaña

GET /campaigns/{campaign_id}/documents

Devuelve los metadatos de cada documento asociado a la campaña (sin el payload de contenido).

Respuesta

{
  "data": {
    "campaign_id": "cmp_abc",
    "documents": [
      {
        "id": "doc_001",
        "campaign_id": "cmp_abc",
        "display_name": "Campaign Brief",
        "name": "Campaign Brief",
        "file_type": "campaign_brief",
        "type": "campaign_brief",
        "folder_path": "/brief",
        "status": "completed",
        "version": 2,
        "current_version": 2,
        "created_at": "2026-04-01T10:00:00Z",
        "updated_at": "2026-04-05T11:00:00Z"
      }
    ],
    "count": 1
  }
}

Obtener documento de la campaña

GET /campaigns/{campaign_id}/documents/{document_id}

Devuelve el contenido completo del documento.

Ejemplo

cURL

curl "https://be.graph8.com/api/v1/campaigns/cmp_abc/documents/doc_001" \
  -H "Authorization: Bearer $API_KEY"

Respuesta

{
  "data": {
    "id": "doc_001",
    "campaign_id": "cmp_abc",
    "name": "Campaign Brief",
    "type": "campaign_brief",
    "status": "completed",
    "version": 2,
    "content": "# Campaign Brief\n\nGoal: ...",
    "created_at": "2026-04-01T10:00:00Z",
    "updated_at": "2026-04-05T11:00:00Z"
  }
}

Crear documento de campaña

POST /campaigns/{campaign_id}/documents

Crea un nuevo documento adjunto a la campaña.

Cuerpo de la solicitud

Campo	Tipo	Requerido	Descripción
`file_type`	string	Sí	Tipo de documento (`campaign_brief`, `sequence`, `step_catalog`, etc.)
`display_name`	string	Sí	Nombre legible para humanos
`content`	string	No	Contenido del documento (predeterminado `""`)
`folder_path`	string	No	Ruta de carpeta opcional
`status`	string	No (predeterminado `draft`)	Estado del documento

Respuesta `201 Created`

Devuelve la misma estructura de documento que GET .../documents/{document_id}.

Actualizar documento de campaña

PUT /campaigns/{campaign_id}/documents/{document_id}

Actualiza el contenido. Incrementa version y current_version en 1, y registra completed=true y generating=false en los metadatos.

Cuerpo de la solicitud

Campo	Tipo	Descripción
`content`	string	Nuevo contenido (mantiene el existente si está vacío)
`status`	string	Anulación de estado opcional
`structured_data`	object	Payload estructurado opcional almacenado en los metadatos

Errores

Estado	Significado
`404`	Documento no encontrado (o su campaña principal está archivada)

Eliminar documento de campaña

DELETE /campaigns/{campaign_id}/documents/{document_id}

Eliminación permanente. Devuelve 404 si no se encuentra el documento o su campaña principal.

Respuesta

{ "data": { "status": "deleted", "document_id": "doc_001" } }

Obtener secuencia

GET /campaigns/{campaign_id}/sequence

Devuelve tanto el documento de secuencia (lista ordenada de referencias de pasos) como el documento de catálogo de pasos (definiciones de pasos identificadas por step_id).

Respuesta

{
  "data": {
    "campaign_id": "cmp_abc",
    "sequence": {
      "steps": [
        {"step_id": "step_1", "day": 0, "condition": null, "stop_on_reply": true},
        {"step_id": "step_2", "day": 3, "condition": "no_reply", "stop_on_reply": true}
      ]
    },
    "step_catalog": {
      "steps": {
        "step_1": {"name": "Intro email", "channel": "email", "mode": "send", ...},
        "step_2": {"name": "LinkedIn follow-up", "channel": "linkedin", "mode": "send", ...}
      }
    },
    "sequence_doc_id": "doc_seq_001",
    "catalog_doc_id": "doc_cat_001"
  }
}

Errores

Estado	Significado
`404`	Campaña no encontrada

Actualizar secuencia

PUT /campaigns/{campaign_id}/sequence

Reemplaza la lista ordenada de referencias de pasos. Cada step_id debe existir en el catálogo de pasos.

Cuerpo de la solicitud

Campo	Tipo	Requerido	Descripción
`steps`	object[]	Sí	Referencias ordenadas de pasos

Cada elemento step:

Campo	Tipo	Descripción
`step_id`	string	ID del paso (debe existir en el catálogo)
`day`	integer	Desplazamiento en días desde el inicio de la secuencia
`condition`	string	Condición opcional (`no_reply`, etc.)
`stop_on_reply`	boolean	Predeterminado `true`

Errores

Estado	Significado
`400`	`step_id` no está en el catálogo
`404`	Documento de secuencia no encontrado

Crear paso de secuencia

POST /campaigns/{campaign_id}/sequence/steps

Crea un nuevo paso y lo agrega a la secuencia en una sola llamada. El endpoint genera un nuevo step_id (step_N).

Cuerpo de la solicitud

Campo	Tipo	Requerido	Descripción
`name`	string	Sí	Nombre del paso
`channel`	string	Sí	`email`, `linkedin`, `sms`, `phone`, etc.
`mode`	string	Sí	`send`, `manual`, etc.
`day`	integer	Sí	Desplazamiento en días para la ubicación en la secuencia
`platform`	string	No	Plataforma del subcanal
`angle_id`	string	No (predeterminado `angle_1`)	Referencia del ángulo de mensajería
`cta_type`	string	No (predeterminado `soft_ask`)	Tipo de CTA
`personalization_level`	string	No (predeterminado `medium`)	Nivel de personalización
`constraints`	object	No	Diccionario de restricciones
`condition`	string	No	Condición de la secuencia
`stop_on_reply`	boolean	No (predeterminado `true`)	Detiene la inscripción del contacto al recibir respuesta

Respuesta `201 Created`

{
  "data": {
    "status": "created",
    "step_id": "step_3",
    "step": {
      "step_id": "step_3",
      "name": "Final follow-up",
      "channel": "email",
      "mode": "send",
      "platform": null,
      "angle_id": "angle_1",
      "cta_type": "soft_ask",
      "personalization_level": "medium",
      "constraints": {}
    },
    "day": 7
  }
}

Actualizar paso de secuencia

PUT /campaigns/{campaign_id}/sequence/steps/{step_id}

Actualiza la definición de un paso en el catálogo y, opcionalmente, su ubicación en la secuencia. Todos los campos son opcionales: envíe solo los que desee modificar.

Cuerpo de la solicitud

Campo	Tipo	Descripción
`name`	string	Nombre del paso
`channel`	string	Canal
`mode`	string	Modo
`platform`	string	Plataforma
`angle_id`	string	Ángulo de mensajería
`cta_type`	string	Tipo de CTA
`personalization_level`	string	Nivel
`constraints`	object	Diccionario de restricciones
`do_not_send_rules`	string[]	Reglas que deben suprimir el envío
`day`	integer	Ubicación en la secuencia (actualiza el documento de secuencia, no el catálogo)
`condition`	string	Condición de ubicación en la secuencia
`stop_on_reply`	boolean	Anulación de ubicación en la secuencia

Los campos day, condition y stop_on_reply modifican el documento de secuencia; el resto modifica la entrada del catálogo.

Errores

Estado	Significado
`404`	Paso o catálogo de pasos no encontrado

Eliminar paso de secuencia

DELETE /campaigns/{campaign_id}/sequence/steps/{step_id}

Elimina un paso del catálogo y todas sus referencias en la secuencia.

Respuesta

{ "data": { "status": "deleted", "step_id": "step_3" } }

Errores

Estado	Significado
`404`	Paso no encontrado

Lanzar campaña

POST /campaigns/{campaign_id}/launch

Advertencia: pone en cola prospección real hacia contactos reales en los canales vinculados. El endpoint responde de inmediato con el estado launch_queued; utilice la CLI de spine (g8 watch) o su propio sondeo contra /sequences/{id} para monitorear el progreso.

Ejemplo

cURL

curl -X POST "https://be.graph8.com/api/v1/campaigns/cmp_abc/launch" \
  -H "Authorization: Bearer $API_KEY"

Respuesta

{
  "data": {
    "status": "launch_queued",
    "campaign_id": "cmp_abc",
    "message": "Campaign launch has been queued. Use g8 watch to monitor progress."
  }
}

Campañas GTM

Listar campañas

Parámetros de consulta

Ejemplo

Respuesta

Crear campaña

Cuerpo de la solicitud

Ejemplo

Respuesta

Listar ideas de campaña

Parámetros de consulta

Respuesta

Obtener campaña

Ejemplo

Respuesta

Errores

Actualizar campaña

Cuerpo de la solicitud

Errores

Listar documentos de la campaña

Respuesta

Obtener documento de la campaña

Ejemplo

Respuesta

Crear documento de campaña

Cuerpo de la solicitud

Respuesta 201 Created

Actualizar documento de campaña

Cuerpo de la solicitud

Errores

Eliminar documento de campaña

Respuesta

Obtener secuencia

Respuesta

Errores

Actualizar secuencia

Cuerpo de la solicitud

Errores

Crear paso de secuencia

Cuerpo de la solicitud

Respuesta 201 Created

Actualizar paso de secuencia

Cuerpo de la solicitud

Errores

Eliminar paso de secuencia

Respuesta

Errores

Lanzar campaña

Ejemplo

Respuesta

Respuesta `201 Created`

Respuesta `201 Created`