Graph SDK - Starter Kit

The Anyshift Graph SDK gives TypeScript applications a small, typed client for querying your infrastructure graph. Use it for dashboards, incident workflows, CI checks, deployment automation, or any service that needs direct graph answers without going through the Annie chat interface.

The first public SDK release is TypeScript. Python and Go SDKs will follow.

Install

npm install @anyshift/graph-sdk

The SDK works in Node.js 18+ and modern runtimes that provide fetch.

Authenticate

Create an API token in Anyshift, then pass it with the project you want to query:

import { GraphAnswer } from "@anyshift/graph-sdk";

const graph = new GraphAnswer({
  token: process.env.ANYSHIFT_API_TOKEN!,
  project: process.env.ANYSHIFT_PROJECT_ID!,
});

By default the SDK connects to https://graph.anyshift.io.

Query the Graph

Use typed helpers for common graph questions:

const events = await graph.events({ since: "1h", limit: 10 });
console.log(events.summary);

const blast = await graph.blast({ resource: "checkout" });
console.log(blast.summary);

const path = await graph.path({ from: "checkout", to: "checkout-postgres" });
console.log(path.summary);

Render Topology

Topology queries return graph nodes and edges. Convert them to Mermaid when you want to embed a diagram in a report, pull request, runbook, or incident update:

import { GraphAnswer, toMermaid } from "@anyshift/graph-sdk";

const graph = new GraphAnswer({
  token: process.env.ANYSHIFT_API_TOKEN!,
  project: process.env.ANYSHIFT_PROJECT_ID!,
});

const topology = await graph.topology({
  service: "checkout",
  level: "container",
});

console.log(toMermaid(topology));

Use level: "dynamic" to render a sequence diagram. Other topology levels render as flowcharts.

Raw SQL

For advanced use cases, call the Graph API query endpoint directly with Anyshift graph SQL:

const result = await graph.query(
  "SELECT * FROM connections WHERE resource = checkout"
);

console.log(result.summary);

Capabilities

The SDK covers dependency analysis, operational timelines, topology diagrams, Kubernetes safety, security exposure, observability gaps, service dependencies, and GitOps ownership. See Graph SDK Capabilities for the developer-oriented overview, or the canonical CAPABILITIES.md matrix in GitHub for every helper, intent, parameter family, and output category.

Error Handling

The SDK throws typed errors for authentication, bad queries, and unexpected API responses:

import { AuthError, BadQueryError, GraphAnswerError } from "@anyshift/graph-sdk";

try {
  await graph.query("SELECT * FROM connections WHERE resource = checkout");
} catch (error) {
  if (error instanceof AuthError) {
    // Refresh or replace the API token.
  } else if (error instanceof BadQueryError) {
    // Fix the graph SQL or helper parameters.
  } else if (error instanceof GraphAnswerError) {
    // Inspect error.status, error.code, and error.message.
  }
}

Examples and Source

The SDK source, examples, and OpenAPI contract are available in the public GitHub repository: anyshift-io/anyshift-graph-sdk.

Troubleshooting

401 Unauthorized

Check that ANYSHIFT_API_TOKEN is set and that the token has access to the selected project.

Project not found or no graph data

Check that ANYSHIFT_PROJECT_ID points to the project you intend to query and that the project has completed ingestion.

The query returns no rows

Start with a broader helper such as graph.events({ since: "24h" }) or graph.connections({ resource: "<service-name>" }), then narrow the query once you confirm the exact service or resource name.

​Install

​Authenticate

​Query the Graph

​Render Topology

​Raw SQL

​Capabilities

​Error Handling

​Examples and Source

​Troubleshooting

Install

Authenticate

Query the Graph

Render Topology

Raw SQL

Capabilities

Error Handling

Examples and Source

Troubleshooting