OpenAPI and client tools

GraphJSON publishes a machine-readable description of the documented public HTTP API.

• Download OpenAPI 3.1 JSON
• Download the Postman collection

The files cover:

POST /api/log
POST /api/bulk-log
POST /api/visualize/data
POST /api/visualize/iframe
POST /api/visualize/embed

The prose API reference remains the source for operational guidance, security decisions, examples, and current limitations. The OpenAPI file supplies request and response shapes for tooling.

The Data API intentionally returns several row shapes. Read Data API response contracts before generating a native analytics client, and validate your own events with Executable event contracts.

What the contract provides#

Use it to:

• inspect endpoint and field schemas
• generate TypeScript or other client types
• validate test fixtures
• import requests into API tools
• build contract tests
• compare API changes in source control

The file does not create an official GraphJSON SDK or change the compatibility policy.

Authentication in the schema#

GraphJSON currently authenticates with api_key inside the JSON request body.

{
  "api_key": "your_api_key"
}

Because this is not an HTTP Bearer or header scheme, the OpenAPI operations model api_key as a required request property rather than an OpenAPI security scheme.

Security: Generated examples can contain placeholder keys. Never commit a real workspace key to the generated client, fixture, exported environment, or API-tool collection.

Import into Postman#

1. Download the GraphJSON Postman collection.
2. Import the file.
3. Set the collection variable api_key in a private local environment.
4. Keep base_url as https://api.graphjson.com.
5. Change the sample collection and event names.
6. Send a test event to a non-production collection.

Do not sync an environment containing the real API key to a public workspace.

The collection includes requests for single ingestion, bulk ingestion, data retrieval, iframe generation, and iframe/image generation.

Generate TypeScript types#

One common workflow:

npx openapi-typescript \
  https://graphjson.com/graphjson-openapi.json \
  --output graphjson-api.d.ts

Pin the generated output in your application repository and review changes deliberately. A regenerated type file should not be deployed without reading the GraphJSON API changelog.

Generated types do not add:

• timeouts
• retry policy
• event IDs
• redaction
• queueing
• tenant authorization

Those remain application responsibilities.

Build a thin client#

Keep one transport boundary:

const GRAPHJSON_BASE_URL = "https://api.graphjson.com";

async function graphJSONPost<T>(
  path: string,
  body: Record<string, unknown>
): Promise<T> {
  const response = await fetch(`${GRAPHJSON_BASE_URL}${path}`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      ...body,
      api_key: process.env.GRAPHJSON_API_KEY
    }),
    signal: AbortSignal.timeout(10_000)
  });

  const text = await response.text();

  if (!response.ok) {
    throw new Error(
      `GraphJSON ${response.status}: ${text.slice(0, 300)}`
    );
  }

  return text ? JSON.parse(text) : (null as T);
}

Do not accept an arbitrary path and request body from a browser. Application code should expose purpose-specific functions:

logProductEvent(...)
loadAuthorizedUsageReport(...)
generateTenantDashboard(...)

Validate an event fixture#

The OpenAPI file validates the transport envelope, not your internal event schema.

Add an application schema too:

type SignupCompleted = {
  event: "signup_completed";
  event_id: string;
  user_id: string;
  account_id: string;
  schema_version: 1;
};

Then validate:

1. application event contract
2. JSON serialization
3. GraphJSON logging request shape

The GraphJSON API can accept flexible JSON while your producer still enforces a strict product contract.

Contract-test ingestion#

Use a disposable test collection:

it("accepts a documented event envelope", async () => {
  const response = await fetch(
    "https://api.graphjson.com/api/log",
    {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        api_key: process.env.GRAPHJSON_TEST_API_KEY,
        collection: "contract_test_events",
        timestamp: Math.floor(Date.now() / 1000),
        json: JSON.stringify({
          event: "contract_test_completed",
          event_id: crypto.randomUUID(),
          schema_version: 1
        })
      })
    }
  );

  expect(response.status).toBeGreaterThanOrEqual(200);
  expect(response.status).toBeLessThan(300);
});

Use a non-production workspace or short-retention collection. Never run a test that writes uncontrolled fixtures into a financial or customer-facing collection.

Test failure behavior#

At minimum:

Do not intentionally generate production rate-limit traffic. Exercise retry logic with a controlled mock and use a minimal live contract test.

Response compatibility#

The schema models documented stable fields and permits additional fields in several responses.

Clients should:

• branch on HTTP status
• tolerate additional response fields
• treat generated URLs as opaque strings
• avoid depending on exact human-readable error text
• handle JSON and plain-text error bodies

This matches the compatibility policy.

What is intentionally excluded#

The machine-readable contract does not include:

• dashboard-internal endpoints
• account and billing implementation endpoints
• alert-evaluation internals
• asynchronous notebook job endpoints
• administrative or maintenance routes
• undocumented fields discovered by inspecting client requests

An endpoint in the repository is not automatically a public API.

Version the contract#

Recommended application workflow:

1. download the OpenAPI file during a deliberate dependency update
2. diff it with the pinned copy
3. read the changelog
4. regenerate types
5. run contract and application tests
6. deploy during the documented transition

Do not fetch the schema on every production request.

Report a schema mismatch#

If the live documented endpoint and OpenAPI file disagree, send:

• endpoint
• approximate time and time zone
• redacted request shape
• HTTP status
• redacted response shape
• expected schema section

Never include the workspace key or a complete private payload.

Continue with API overview, Authentication, and Errors and limits.