🛠️API

Empower your integrations with the flexibility of GraphQL on Graph Commons.

The Graph Commons API provides developers with a powerful GraphQL interface to integrate, query, and manage data. With this API, you can automate processes, dive deep into your networks, and harness the full potential of Graph Commons directly from your applications.

GraphQL API Explorer

You can build queries, browse schemas, and test the API using the Apollo GraphQL Explorer:

👉🏼 Open in Apollo Explorer

Try our Graph Commons API directly in the Apollo GraphQL Explorer

Authentication

No separate API key required, simply use your Graph Commons username and password to authenticate.

API authentication is done with your email and password. Social logins are not supported.

Here’s a Node.js function to authenticate and retrieve a JWT token:

export const login = async (username: string, password: string) => {
  const response = await fetch("https://graphcommons.com/graphql", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      query: `mutation login($username: ID!, $password: String!) {
        JWT: login(loginOrEmail: $username, password: $password)
      }`,
      variables: {
        username,
        password,
      },
    }),
  });

  if (!response.ok) {
    throw new Error(`HTTP error! Status: ${response.status}`);
  }

  const jsonResponse = await response.json();
  return jsonResponse.data.JWT;
};

Create a graph

Use the login function from the authentication step to create a new graph.

You can send your own temporary IDs for node types, edge types, nodes, and edges. The server will return an idsMapping so you can map your temp IDs to real server IDs later.

import { login } from './path_to_login_function';

const USERNAME = process.env.GC_USERNAME!;
const PASSWORD = process.env.GC_PASSWORD!;

async function createSimpleGraph() {
  const jwt = await login(USERNAME, PASSWORD);

  // 1) Define your graph in simple JSON.
  // Use YOUR OWN temp IDs (nt_*, et_*, n_*, e_*).
  const graphInput = {
    name: "Company Mini-Graph",
    description: "A tiny example created via GraphQL API",

    // --- Node Types ---
    nodeTypes: [
      { id: "nt_person",    name: "Person",      properties: [{ id: "p_title",  name: "title",  type: "STRING" }] },
      { id: "nt_company",   name: "Company",     properties: [{ id: "p_domain", name: "domain", type: "STRING" }] },
    ],

    // --- Edge Types ---
    // IMPORTANT: sourceNodeTypeId / targetNodeTypeId must reference your temp nodeType IDs above.
    edgeTypes: [
      {
        id: "et_works_at",
        name: "WORKS_AT",
        sourceNodeTypeId: "nt_person",
        targetNodeTypeId: "nt_company",
        properties: [{ id: "p_since", name: "since", type: "NUMBER" }],
      },
    ],

    // --- Nodes ---
    // Each node's typeId references your temp node type IDs.
    nodes: [
      { id: "n_alex",  name: "Alex",  typeId: "nt_person",  properties: { title: "CTO" } },
      { id: "n_acme",  name: "Acme",  typeId: "nt_company", properties: { domain: "acme.example" } },
    ],

    // --- Edges ---
    // sourceId / targetId reference your temp node IDs; typeId references your temp edge type ID.
    edges: [
      {
        id: "e_alex_acme",
        sourceId: "n_alex",
        targetId: "n_acme",
        typeId: "et_works_at",
        weight: 1,
        properties: { since: 2020 },
      },
    ],
  };

  // 2) Send the createGraph mutation with your JSON.
  const response = await fetch("https://graphcommons.com/graphql", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${jwt}`,
    },
    body: JSON.stringify({
      operationName: "CreateGraph",
      query: `
        mutation CreateGraph($graph: GraphInput!) {
          result: createGraph(graph: $graph) {
            idsMapping {
              graph
              nodeTypes
              nodeTypeProperties
              edgeTypes
              edgeTypeProperties
              nodes
              edges
              __typename
            }
            limitations { usage max __typename }
            report { success errors warnings __typename }
            __typename
          }
        }
      `,
      variables: { graph: graphInput },
    }),
  });

  const json = await response.json();

  if (json.errors) {
    console.error("GraphQL errors:", json.errors);
    throw new Error("createGraph failed at transport level");
  }
  const { report, idsMapping } = json.data.result;

  if (!report.success) {
    console.error("createGraph errors:", report.errors);
    throw new Error(`createGraph failed: ${report.errors.join("\n")}`);
  }

  // You’ll need this for future updates:
  const realGraphId = idsMapping.graph;
  console.log("Created graph id:", realGraphId);

  // Optional: map your temp IDs -> real IDs if you’ll reference them later
  // e.g., const realAlexId = idsMapping.nodes["n_alex"];

  return { graphId: realGraphId, idsMapping };
}

// Example call:
createSimpleGraph().then(({ graphId }) => {
  console.log("Graph ready:", graphId);
});

Read a graph

Use the login function from the authentication step together with a graphId—either returned from the createGraph step or any existing graph on Graph Commons—to fetch graph data.

async function readGraph(graphId: string) {
  const jwt = await login(USERNAME, PASSWORD);

  const res = await fetch("https://graphcommons.com/graphql", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${jwt}`,
    },
    body: JSON.stringify({
      operationName: "GetGraphById",
      query: `
        query GetGraphById($graphId: ID!) {
          result: getGraphById(id: $graphId) {
            graph {
              id
              name
              nodeTypes { id name properties { id name type } }
              edgeTypes { id name sourceNodeTypeId targetNodeTypeId properties { id name type } }
              nodes { id name typeId properties }
              edges {
                id sourceId targetId typeId
                source { name }
                target { name }
                type { name }
                weight
                properties
              }
            }
          }
        }
      `,
      variables: { graphId },
    }),
  });

  const json = await res.json();
  return json.data.result.graph;
}

Update a graph

You can update an existing graph—adding or removing nodes, edges, properties, or adjusting node positions—using the updateGraph mutation.

Call savePatchGraph(id, patch) to create new items and/or update graph properties (such as nodesPosition). The create section should use temporary IDs, which the server will map to permanent ones in the returned idsMapping.

async function addEmployeeToCompany(graphId: string) {
  const jwt = await login(USERNAME, PASSWORD);

  // In this example, we add "Sam" (Person) working at "Acme" (Company),
  // and we move Alex slightly on the canvas.
  //
  // If you don't know the real type IDs, you can just reuse your original temp IDs
  // ONLY IF you've reset and recreated the graph in one go. Otherwise, read the
  // graph first to resolve the real type IDs. For brevity, we assume:
  //  - Person type = the real id behind your original "nt_person"
  //  - Company type = the real id behind your original "nt_company"
  //  - WORKS_AT type = the real id behind "et_works_at"
  //
  // To be explicit, you can fetch the graph (readGraph) and find the type IDs by name.

  // Example: pretend we looked them up:
  const PERSON_TYPE_ID  = "REPLACE_WITH_REAL_PERSON_TYPE_ID";
  const COMPANY_TYPE_ID = "REPLACE_WITH_REAL_COMPANY_TYPE_ID";
  const WORKS_AT_TYPE_ID = "REPLACE_WITH_REAL_WORKS_AT_TYPE_ID";

  // We'll reference Acme by its REAL node id (recommended). If you don’t know it,
  // call readGraph(graphId) and match by name.
  const ACME_NODE_ID = "REPLACE_WITH_REAL_ACME_NODE_ID";
  const ALEX_NODE_ID = "REPLACE_WITH_REAL_ALEX_NODE_ID";

  const patch = {
    id: graphId,
    patch: {
      create: {
        // New node with temp id "n_sam"
        nodes: [
          { id: "n_sam", name: "Sam", typeId: PERSON_TYPE_ID, properties: { title: "Engineer" } },
        ],
        edges: [
          // New edge from "n_sam" (temp) to Acme (real)
          { id: "e_sam_acme", sourceId: "n_sam", targetId: ACME_NODE_ID, typeId: WORKS_AT_TYPE_ID, weight: 1, properties: { since: 2024 } },
        ],
      },
      update: {
        graph: {
          nodesPosition: {
            // Move Alex a bit (use REAL Alex ID here)
            [ALEX_NODE_ID]: { x: 130, y: 110 },
          },
        },
      },
    },
  };

  const res = await fetch("https://graphcommons.com/graphql", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${jwt}`,
    },
    body: JSON.stringify({
      operationName: "SavePatchGraph",
      query: `
        mutation SavePatchGraph($id: ID!, $patch: GraphPatchInput!) {
          result: savePatchGraph(id: $id, patch: $patch) {
            report { success errors warnings __typename }
            idsMapping {
              nodeTypes
              nodeTypeProperties
              edgeTypes
              edgeTypeProperties
              nodes
              edges
              __typename
            }
            limitations { usage max __typename }
            __typename
          }
        }
      `,
      variables: patch,
    }),
  });

  const json = await res.json();
  if (json.errors) {
    console.error("GraphQL errors:", json.errors);
    throw new Error("savePatchGraph failed at transport level");
  }

  const { report, idsMapping } = json.data.result;
  if (!report.success) {
    console.error("savePatchGraph errors:", report.errors);
    throw new Error(`savePatchGraph failed: ${report.errors.join("\n")}`);
  }

  // New real IDs for just-created node/edge are in idsMapping
  console.log("Created (mapped) nodes:", idsMapping.nodes);
  console.log("Created (mapped) edges:", idsMapping.edges);
}

Reset a graph

If you want to clear all nodes and edges while preserving the existing node/edge types and their colors, call resetGraph first. Then, use savePatchGraph with create blocks to re-populate the graph.

async function resetGraphContents(graphId: string) {
  const jwt = await login(USERNAME, PASSWORD);

  const res = await fetch("https://graphcommons.com/graphql", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${jwt}`,
    },
    body: JSON.stringify({
      operationName: "resetGraph",
      query: `
        mutation resetGraph($id: String!) {
          result: resetGraph(id: $id) {
            report { success errors warnings __typename }
            __typename
          }
        }
      `,
      variables: { id: graphId },
    }),
  });

  const json = await res.json();
  const { report } = json.data.result;
  if (!report.success) {
    throw new Error(`resetGraph failed: ${report.errors.join("\n")}`);
  }
}

Tips & Gotchas

• Temp IDs in creates: In createGraph and the create section of savePatchGraph, you can use any string IDs (e.g., n_sam, et_works_at). The server returns an idsMapping to translate these to real IDs. Store them if you’ll reference the same items later.

• Referencing existing items: When modifying existing nodes/edges, use the real IDs (from idsMapping or from a getGraphById read).

• Positions: Set positions with either the temp node IDs (during createGraph) or the real node IDs (when updating).

• Types vs. Instances: nodeTypes/edgeTypes define the schema. nodes/edges are your data. After a reset, types remain; nodes/edges are cleared.

• Errors: Always check report.success and surface report.errors in logs for faster debugging.

Next steps

• Learn more about GraphQL queries

• Explore queries and mutations in the Graph Commons API with the Apollo Explorer.