OpenSearch (Raw Data Access)

These endpoints provide generic, read-only, structured access to the graph8 mashup OpenSearch indices. They back the g8_opensearch_* MCP tool family. Use them when the higher-level CRM or prospecting endpoints (/contacts, /companies, /enrichment/*, /search/contacts) don’t expose the field you need to filter on.

The search, count, and aggregate routes require an active subscription (same gate as /search/contacts and /enrichment/enrich). The resolve route does not.

Search

POST /opensearch/search

Structured search across a whitelisted set of mashup indices. The request body declares filters, fields, sort, and limit as typed inputs — the handler translates them into a safe bool/term OpenSearch query. Raw OpenSearch DSL is not accepted.

Request Body

Example

curl -X POST "https://be.graph8.com/api/v1/opensearch/search" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "index": "mashup_contacts",
    "filters": {
      "COMPANY_DOMAIN": "acme.com",
      "COMPANY_INDUSTRY": ["SaaS", "Fintech"]
    },
    "fields": ["COMPANY_DOMAIN", "CONTACT_ID"],
    "sort": [{ "COMPANY_REVENUE": "desc" }],
    "limit": 50,
    "cursor": null,
    "track_total_hits": null
  }'

Response

{
  "data": {
    "index": "mashup_contacts",
    "total": 1,
    "hits": [
      {
        "id": "abc",
        "score": 1.5,
        "source": { "COMPANY_DOMAIN": "acme.com" },
        "sort": [42]
      }
    ],
    "cursor": [42],
    "took_ms": 7
  }
}

Count

POST /opensearch/count

Exact document count for a whitelisted index using the native OpenSearch _count API — not subject to the 10000 track_total_hits ceiling. Uses the same index and filters shape as search; paging fields are intentionally absent because a count returns no rows. This is the correct call for TAM cell sizing.

Request Body

Example

curl -X POST "https://be.graph8.com/api/v1/opensearch/count" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "index": "mashup_companies",
    "filters": {
      "COMPANY_NAICS": ["3311", "3311.00000"],
      "COMPANY_COUNTRY": ["US", "United States"]
    }
  }'

Response

{ "data": { "index": "mashup_companies", "count": 17842 } }

Aggregate

POST /opensearch/aggregate

Generic, allowlist-bounded GROUP BY — the TAM matrix-walk primitive. Translates group_by into nested OpenSearch terms aggregations with metric sub-aggregations, then applies having, sort, and limit to the flattened groups.

Request Body

agg object fields

Example

curl -X POST "https://be.graph8.com/api/v1/opensearch/aggregate" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "index": "mashup_companies",
    "filters": {
      "COMPANY_NAICS": ["3311", "3311.00000"]
    },
    "group_by": ["COMPANY_STATE", "COMPANY_EMPLOYEE_COUNT"],
    "agg": [
      { "function": "count" },
      { "function": "uniqExact", "field": "COMPANY_DOMAIN", "alias": "unique_domains" }
    ],
    "having": { "count": { "gte": 50 } },
    "sort": [{ "count": "desc" }],
    "limit": 500
  }'

Response

{
  "data": {
    "index": "mashup_companies",
    "groups": [
      {
        "key": { "COMPANY_STATE": "OH", "COMPANY_EMPLOYEE_COUNT": "11-50" },
        "agg": { "count": 1247, "unique_domains": 1184 }
      }
    ],
    "total_groups": 312,
    "took_ms": 84
  }
}

Resolve

POST /opensearch/resolve

Bulk HEM-to-contact-ID or IP-to-company-ID resolution, optimised for batches up to 500. The response includes every input as a key — null for misses — so callers can iterate results without re-querying.

This endpoint does not require an active subscription.

Request Body

Example

curl -X POST "https://be.graph8.com/api/v1/opensearch/resolve" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "hem_to_contact",
    "ids": ["sha256hash1", "sha256hash2"]
  }'

Response

{
  "data": {
    "kind": "hem_to_contact",
    "results": {
      "sha256hash1": "C1",
      "sha256hash2": null
    },
    "matched": 1,
    "requested": 2
  }
}