GTM Context

These endpoints expose the org’s GTM context — the same data Studio uses to author campaigns. Use them from AI agents (MCP), CLI tools, or integrations to ground campaign generation in your specific brand, ICPs, and recent activity.

For machine-readable schemas see the interactive API docs.

List Global Context Documents

GET /global-context/documents

Returns the org’s global context documents. Each org has 44 of these total: 21 context docs (brand brief, value props, personas, ICPs, messaging house, etc.), 16 intelligence docs (website scrape, competitor data, keywords), 6 research reports, and 1 campaign intelligence brief.

Query Parameters

Example

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

Response

{
  "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"
    }
  ]
}

Documents are sorted by priority DESC, updated_at DESC.

Update Global Context Document

PATCH /global-context/documents/{doc_id}

Update a Context-bucket document. The request is partial — send at least one of content or status. Each save records a DocumentVersion snapshot (same as the in-app Studio editor, so history is consistent across UI, API, and MCP).

Path Parameters

Request Body

Example

curl -X PATCH "https://be.graph8.com/api/v1/global-context/documents/ctx_001" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Updated brand brief body...",
    "status": "completed"
  }'

Response

{
  "data": {
    "id": "ctx_001",
    "display_name": "Brand Brief",
    "file_type": "brand_brief",
    "category": "brand",
    "status": "completed",
    "version_number": 4,
    "content": "Updated brand brief body...",
    "updated_at": "2026-04-11T09:00:00Z"
  }
}

Errors

List Personas

GET /personas

Returns campaign-builder personas (target buyer profiles with messaging signals).

Query Parameters

Example

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

Response

{
  "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"
    }
  ]
}

Sorted: pinned first, then by priority ASC, updated_at DESC.

List ICPs

GET /icps

Returns Ideal Customer Profiles (firmographic + signal definitions used to find target accounts).

Query Parameters

Example

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

Response

{
  "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"
    }
  ]
}

List Mailboxes

GET /mailboxes

Returns sending mailboxes connected to the org, including warmup status from the configured provider.

Query Parameters

Example

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

Response

{
  "data": [
    {
      "id": "mbx_001",
      "email": "[email protected]",
      "display_name": "Rep Name",
      "provider": "gmail",
      "source": "oauth",
      "connection_status": "active",
      "is_archived": false,
      "shared_with_team": false,
      "team_id": null,
      "team_name": null,
      "daily_limit": 50,
      "created_by": "user_x",
      "created_at": "2026-01-01T00:00:00Z",
      "updated_at": "2026-04-10T14:30:00Z",
      "warmup_provider": "smartlead",
      "warmup_status": "active",
      "smartlead_warmup_enabled": true
    }
  ]
}

Get Mailbox Warmup

GET /mailboxes/{mailbox_id}/warmup

Live provider fetch for warmup analytics and settings for a specific mailbox.

Path Parameters

Example

curl "https://be.graph8.com/api/v1/mailboxes/mbx_001/warmup" \
  -H "Authorization: Bearer $API_KEY"

Response

{
  "success": true,
  "warmup_enabled": true,
  "provider": "smartlead",
  "analytics": {},
  "warmup_settings": {}
}

List Intelligence Data

GET /intelligence-data

Returns machine-generated intelligence documents for the org. This bucket is intentionally read-only — it is machine-generated and has no manual-edit path.

Query Parameters

Example

curl "https://be.graph8.com/api/v1/intelligence-data?data_type=website_scrape" \
  -H "Authorization: Bearer $API_KEY"

Response

{
  "data": [
    {
      "id": "int_001",
      "website_url": "https://acme.com",
      "data_type": "website_scrape",
      "status": "completed",
      "data": {},
      "collected_at": "2026-03-01T08:00:00Z",
      "created_at": "2026-03-01T08:05:00Z",
      "updated_at": "2026-03-01T08:05:00Z"
    }
  ]
}

List Research Reports

GET /research-reports

Returns AI-generated research reports for the org (buyer psychology, competitive teardown, GTM channel analysis, etc.).

Query Parameters

Example

curl "https://be.graph8.com/api/v1/research-reports?report_type=buyer_psychology" \
  -H "Authorization: Bearer $API_KEY"

Response

{
  "data": [
    {
      "id": "rpt_001",
      "website_url": "https://acme.com",
      "report_type": "buyer_psychology",
      "report_number": 1,
      "status": "completed",
      "content": {},
      "markdown_content": "# Buyer Psychology Report\n\n...",
      "created_at": "2026-03-05T10:00:00Z",
      "updated_at": "2026-04-01T14:30:00Z"
    }
  ]
}

Update Research Report

PATCH /research-reports/{report_id}

Update a Research-bucket report. The request is partial — send at least one of markdown_content or status. Editing markdown_content records a DocumentVersion snapshot and re-indexes the report to RAG so search stays fresh.

Path Parameters

Request Body

Example

curl -X PATCH "https://be.graph8.com/api/v1/research-reports/rpt_001" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "markdown_content": "# Updated Buyer Psychology Report\n\n...",
    "status": "approved"
  }'

Response

{
  "data": {
    "id": "rpt_001",
    "report_type": "buyer_psychology",
    "status": "approved",
    "version_number": 2,
    "markdown_content": "# Updated Buyer Psychology Report\n\n...",
    "updated_at": "2026-04-12T10:00:00Z"
  }
}

version_number is null when only status changed (no content snapshot is recorded for status-only updates).

Errors

List Activities

GET /activities

Returns recent CRM activities (calls, meetings, emails, notes) across the org.

Query Parameters

Example

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

Response

{
  "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"
    }
  ]
}

Sorted by activity_date DESC.