# Contexto GTM

> Consulte documentos de contexto global, personas, ICP y actividades recientes

Source: https://docs.graph8.com/es/developers/gtm-context/

Estos endpoints exponen el contexto GTM de la organización: los mismos datos que Studio utiliza para crear campañas. Son de solo lectura y los consumen agentes de IA (MCP) y herramientas CLI para fundamentar la generación de campañas en su marca, ICP y actividad reciente específicos.

| Endpoint | Método | Descripción |
|----------|--------|-------------|
| `/global-context/documents` | GET | Lista los documentos de contexto global (44 por organización: brief de marca, propuestas de valor, etc.) |
| `/personas` | GET | Lista las personas del constructor de campañas |
| `/icps` | GET | Lista los Perfiles de Cliente Ideal |
| `/activities` | GET | Lista las actividades recientes del CRM |

Para consultar los esquemas legibles por máquina, vea la [documentación interactiva de la API](https://be.graph8.com/api/v1/docs).

---

## Listar Documentos de Contexto Global

`GET /global-context/documents`

Devuelve los documentos de contexto global de la organización. Cada organización cuenta con 44 en total: 21 documentos de contexto (brief de marca, propuestas de valor, personas, ICP, casa de mensajería, etc.), 16 documentos de inteligencia (scraping del sitio web, datos de competidores, palabras clave), 6 informes de investigación y 1 brief de inteligencia de campañas.

### Parámetros de consulta

| Parámetro | Tipo | Predeterminado | Descripción |
|-----------|------|----------------|-------------|
| `category` | string | - | Filtrar por categoría de contexto |
| `limit` | integer | 50 | 1-200 |

### Ejemplo

**cURL**

```bash
curl "https://be.graph8.com/api/v1/global-context/documents?limit=10" \
  -H "Authorization: Bearer $API_KEY"
```

### Respuesta

```json
{
  "data": [
    {
      "id": "ctx_001",
      "display_name": "Brand Brief",
      "file_type": "brand_brief",
      "category": "brand",
      "folder_path": "/context/brand",
      "status": "completed",
      "priority": 100,
      "version": 3,
      "content": "# Acme brand brief\n\nMission: ...",
      "created_at": "2026-03-01T10:00:00Z",
      "updated_at": "2026-04-10T14:30:00Z"
    }
  ]
}
```

Los documentos se ordenan por `priority DESC, updated_at DESC`.

---

## Listar Personas

`GET /personas`

Devuelve las personas del constructor de campañas (perfiles de compradores objetivo con señales de mensajería).

### Parámetros de consulta

| Parámetro | Tipo | Predeterminado | Descripción |
|-----------|------|----------------|-------------|
| `status` | string | - | Filtrar por estado de la persona |
| `limit` | integer | 50 | 1-200 |

### Ejemplo

**cURL**

```bash
curl "https://be.graph8.com/api/v1/personas" \
  -H "Authorization: Bearer $API_KEY"
```

### Respuesta

```json
{
  "data": [
    {
      "id": "per_001",
      "title": "VP of Marketing at mid-market SaaS",
      "priority": 1,
      "confidence": "high",
      "confidence_score": 0.9,
      "why_target": "Owns demand gen budget...",
      "key_signals": ["hiring SDRs", "expanding into NA"],
      "expected_receptivity": "warm",
      "campaign_approach": "Lead with peer proof",
      "recommended_goal": "Book discovery call",
      "status": "approved",
      "pinned": true,
      "source": "studio_generated",
      "created_at": "2026-03-15T10:00:00Z",
      "updated_at": "2026-04-01T14:30:00Z"
    }
  ]
}
```

Orden: primero las ancladas, después por `priority ASC, updated_at DESC`.

---

## Listar ICP

`GET /icps`

Devuelve los Perfiles de Cliente Ideal (definiciones firmográficas y de señales usadas para identificar cuentas objetivo).

### Parámetros de consulta

| Parámetro | Tipo | Predeterminado | Descripción |
|-----------|------|----------------|-------------|
| `status` | string | - | Filtrar por estado del ICP |
| `limit` | integer | 50 | 1-200 |

### Ejemplo

**cURL**

```bash
curl "https://be.graph8.com/api/v1/icps" \
  -H "Authorization: Bearer $API_KEY"
```

### Respuesta

```json
{
  "data": [
    {
      "id": "icp_001",
      "name": "Mid-market SaaS - North America",
      "description": "Series B-D SaaS companies, 100-1000 FTE, US/CA HQ",
      "firmographics": {"employee_min": 100, "employee_max": 1000, "country": ["US", "CA"]},
      "tech_stack": {"required": ["Salesforce"]},
      "buying_signals": ["hiring SDRs", "raised funding"],
      "fit_score": 0.85,
      "opportunity_score": 0.7,
      "readiness_score": 0.8,
      "total_score": 0.78,
      "status": "approved",
      "pinned": false,
      "priority": 2,
      "created_at": "2026-03-15T10:00:00Z",
      "updated_at": "2026-04-01T14:30:00Z"
    }
  ]
}
```

---

## Listar Actividades

`GET /activities`

Devuelve las actividades recientes del CRM (llamadas, reuniones, correos electrónicos, notas) de toda la organización.

### Parámetros de consulta

| Parámetro | Tipo | Predeterminado | Descripción |
|-----------|------|----------------|-------------|
| `activity_type` | string | - | Filtrar por tipo |
| `contact_id` | string | - | Filtrar por un contacto específico |
| `company_id` | string | - | Filtrar por una empresa específica |
| `deal_id` | string | - | Filtrar por una oportunidad específica |
| `limit` | integer | 50 | 1-200 |

### Ejemplo

**cURL**

```bash
curl "https://be.graph8.com/api/v1/activities?activity_type=meeting&limit=20" \
  -H "Authorization: Bearer $API_KEY"
```

### Respuesta

```json
{
  "data": [
    {
      "id": "act_001",
      "activity_type": "meeting",
      "activity_subtype": "discovery_call",
      "subject": "Discovery call with Acme",
      "description": "Walked through current outbound stack...",
      "company_id": "comp_42",
      "deal_id": "deal_7",
      "contact_id": "cont_101",
      "owner_id": "user_5",
      "owner_name": "Jane Rep",
      "activity_date": "2026-04-10T15:00:00Z",
      "duration_minutes": 30,
      "status": "completed",
      "outcome": "qualified",
      "next_steps": "Send pricing options by Friday",
      "extra_data": {},
      "source": "calendar_sync",
      "external_id": "gcal_evt_xyz"
    }
  ]
}
```

Ordenado por `activity_date DESC`.