REST API Overview

The REST API gives you direct HTTP access to contacts, companies, lists, enrichment, search, sequences, webhooks, deals, tasks, notes, fields, quotes, pipelines, workflows, skills, voice, intent, studio, and more. Any language, any platform.

Quick Reference

• Base URL: https://be.graph8.com/api/v1
• Auth: Authorization: Bearer YOUR_API_KEY (details)
• Format: JSON request/response
• Rate limit: 50 req/s + 1,000 req/min per org (details)
• Docs: Interactive Swagger →

30-second start

If you can paste a curl, you can start integrating:

# Will return your stored contacts (or [] if none yet)
curl 'https://be.graph8.com/api/v1/contacts?limit=3' \
  -H "Authorization: Bearer $G8_API_KEY"

import { g8 } from '@graph8/sdk';
g8.init({ apiKey: process.env.G8_API_KEY! });

const { data } = await g8.contacts.list({ limit: 3 });

import httpx, os
r = httpx.get(
    "https://be.graph8.com/api/v1/contacts",
    params={"limit": 3},
    headers={"Authorization": f"Bearer {os.environ['G8_API_KEY']}"},
)
print(r.json())

g8 login
g8 search-contacts --limit 3

Don’t have an API key? Get one in 30 seconds →

API Surfaces

graph8 exposes two distinct HTTP surfaces. Only /api/v1/* is for developers — everything else is internal.

Stick to /api/v1/* unless a doc explicitly tells you otherwise.

CRM: Notes | Tasks | Fields | Deals | Assert/Upsert

Engage: Sequence Lifecycle | Inbox | Meetings | Voice & Dialer | Webhooks

Revenue: Quotes | Stage Checklist Pipelines

Automation: Workflows | Skills | Landing Pages

Intelligence: Intent & Signals | GTM Campaigns | GTM Context

Sync: Audience Syncs | CRM Syncs

Public (browser, write key): Public Endpoints

Reference: Pricing | Pagination | Errors | Rate Limits | REST API FAQ

The graph8 Developer API lets you programmatically discover new prospects, manage your CRM data, and enrich contact information - all through a single REST API.

Events, webhooks & real-time

Subscribe to 40+ event types and graph8 will POST a signed JSON payload to your endpoint as things happen — no polling required.

• Signed — every delivery carries an X-Studio-Signature (HMAC-SHA256 over {X-Studio-Timestamp}.{raw_body}); verify before processing.
• Reliable — failed deliveries retry up to 3× with backoff (10s → 60s → 300s); inspect attempts via GET /webhooks/{id}/deliveries.
• Delivery model — graph8 uses webhook push + REST poll (no SSE/WebSocket today). Full Webhooks reference →.

Rate limits & errors at a glance

Rate limits — 50 req/s + 1,000 req/min per org. Every response (success and 429) carries your quota so you can self-pace:

Full details + backoff code: Rate Limits →.

Errors — standard HTTP status codes with a JSON { "detail": "..." } body (validation errors return a field-level detail array):

Full catalog + handling examples: Errors →.

How Data Works in graph8

graph8 gives you access to two distinct pools of data. Understanding the difference is the key to using the API effectively.

Your data (first-party)

This is data you own — contacts and companies that live in your graph8 workspace. They got there through one of these paths:

• You saved search results from the open data index (via /search/contacts/save)
• You imported contacts from a CSV or CRM integration
• You created them manually via the API (via POST /contacts)
• They were auto-created during enrichment or campaign workflows

You have full read/write access to your data. Query it, update it, delete it, organize it into lists — no credit cost.

Endpoints: /contacts, /companies, /lists

Open data index

This is graph8’s global B2B database — millions of contacts and companies aggregated from multiple data providers. Think of it as a phonebook for the business world: names, titles, emails, phone numbers, company details, and more.

You can search this index with filters (job title, industry, company size, location, etc.) and save matching results into your workspace. Once saved, they become your data.

You can also look up a single person or company by email, LinkedIn URL, or domain.

Open data queries consume credits.

Endpoints: /search/contacts, /search/companies, /enrichment/lookup

The data flow

The typical workflow moves data from open → owned:

┌─────────────────────────────────────────────────────────────────┐
│                                                                 │
│   1. DISCOVER            2. SAVE              3. MANAGE         │
│                                                                 │
│   /search/contacts  ──►  /search/.../save  ──►  /contacts      │
│   /search/companies      (creates a list)       /companies      │
│   /enrichment/lookup                            /lists          │
│                                                                 │
│   Open data index        Moves into your        Full CRUD on    │
│   (read-only, credits)   workspace as a list    your data (free)│
│                                                                 │
│                          4. ENRICH                              │
│                          /enrichment/enrich                     │
│                          Fill missing fields                    │
│                          on your saved contacts                 │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Choosing the Right Endpoint

See Pricing for the full bucket map and plan comparison.

Base URL

https://be.graph8.com/api/v1

All endpoints are relative to this base URL. For example, to list contacts:

GET https://be.graph8.com/api/v1/contacts

Quick Start

export API_KEY="YOUR_API_KEY"

# 1. Search the open data index for CTOs at tech companies
curl -X POST "https://be.graph8.com/api/v1/search/contacts" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filters": [
      {"field": "job_title", "operator": "any_of", "value": ["CTO", "VP Engineering"]},
      {"field": "company_employee_count", "operator": "between", "value": [50, 500]}
    ],
    "limit": 5
  }'

# 2. Save matching contacts to a list in your workspace
curl -X POST "https://be.graph8.com/api/v1/search/contacts/save" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filters": [
      {"field": "job_title", "operator": "any_of", "value": ["CTO", "VP Engineering"]},
      {"field": "company_employee_count", "operator": "between", "value": [50, 500]}
    ],
    "list_title": "Tech CTOs"
  }'

# 3. Query your saved contacts (free, no credits)
curl "https://be.graph8.com/api/v1/contacts?list_id=42&limit=10" \
  -H "Authorization: Bearer $API_KEY"

import requests

API_KEY = "YOUR_API_KEY"
BASE_URL = "https://be.graph8.com/api/v1"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}

# 1. Search the open data index for CTOs at tech companies
results = requests.post(
    f"{BASE_URL}/search/contacts",
    headers=HEADERS,
    json={
        "filters": [
            {"field": "job_title", "operator": "any_of", "value": ["CTO", "VP Engineering"]},
            {"field": "company_employee_count", "operator": "between", "value": [50, 500]}
        ],
        "limit": 5
    }
).json()

print(f"Found {results['pagination']['total']} matches")

# 2. Save matching contacts to a list in your workspace
save = requests.post(
    f"{BASE_URL}/search/contacts/save",
    headers=HEADERS,
    json={
        "filters": [
            {"field": "job_title", "operator": "any_of", "value": ["CTO", "VP Engineering"]},
            {"field": "company_employee_count", "operator": "between", "value": [50, 500]}
        ],
        "list_title": "Tech CTOs"
    }
).json()

list_id = save["data"]["list_id"]

# 3. Query your saved contacts (free, no credits)
contacts = requests.get(
    f"{BASE_URL}/contacts",
    headers=HEADERS,
    params={"list_id": list_id, "limit": 10}
).json()

for c in contacts["data"]:
    print(f"{c['first_name']} {c['last_name']} - {c['work_email']}")

const API_KEY = "YOUR_API_KEY";
const BASE_URL = "https://be.graph8.com/api/v1";
const headers = { Authorization: `Bearer ${API_KEY}`, "Content-Type": "application/json" };

// 1. Search the open data index for CTOs at tech companies
const results = await fetch(`${BASE_URL}/search/contacts`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    filters: [
      { field: "job_title", operator: "any_of", value: ["CTO", "VP Engineering"] },
      { field: "company_employee_count", operator: "between", value: [50, 500] }
    ],
    limit: 5
  }),
}).then(r => r.json());

console.log(`Found ${results.pagination.total} matches`);

// 2. Save matching contacts to a list in your workspace
const save = await fetch(`${BASE_URL}/search/contacts/save`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    filters: [
      { field: "job_title", operator: "any_of", value: ["CTO", "VP Engineering"] },
      { field: "company_employee_count", operator: "between", value: [50, 500] }
    ],
    list_title: "Tech CTOs"
  }),
}).then(r => r.json());

// 3. Query your saved contacts (free, no credits)
const contacts = await fetch(
  `${BASE_URL}/contacts?list_id=${save.data.list_id}&limit=10`,
  { headers: { Authorization: `Bearer ${API_KEY}` } }
).then(r => r.json());

contacts.data.forEach(c =>
  console.log(`${c.first_name} ${c.last_name} - ${c.work_email}`)
);

Endpoint Reference

Discover (open data — credits)

Manage (your data — free)

Reference

Interactive API Reference

For a live, interactive view of all endpoints with request/response schemas, visit the OpenAPI docs:

Open Interactive API Docs →

You can test endpoints directly from the browser — authenticate with your API key and execute requests in real time.

Response Format

All responses use a standard envelope:

{
  "data": { ... },
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 243,
    "has_next": true
  }
}

Single-resource responses include data without pagination. See Pagination for details.