API compatibility and changelog

GraphJSON’s documented API currently uses unversioned endpoint paths such as:

https://api.graphjson.com/api/log
https://api.graphjson.com/api/bulk-log
https://api.graphjson.com/api/visualize/data

You do not need a version header for these endpoints. This page defines how to build resilient clients and how material API changes will be communicated from July 26, 2026 forward.

Compatibility policy#

GraphJSON treats the documented request and response behavior in the API reference as the public contract.

The following changes are normally backward compatible:

adding a new endpoint
adding an optional request field
adding a response field
adding a graph type or customization
adding a new non-success error case for an invalid or unsupported request
changing human-readable error wording
changing internal infrastructure without changing documented behavior

Clients should ignore response fields they do not understand and branch on the HTTP status rather than exact error text.

The following are breaking changes:

removing or renaming a documented endpoint
making an optional field required
removing or renaming a documented request or response field
changing the documented type or meaning of a field
changing authentication requirements
reducing a documented limit in a way that rejects previously valid ordinary requests
changing successful behavior so an integration produces a materially different result

Bug fixes that make behavior match the existing documentation are not necessarily breaking changes. When a bug has become widely depended on, GraphJSON will document the practical migration impact.

How breaking changes will be introduced#

When a breaking API change is necessary, GraphJSON will:

add an entry to this changelog
document the affected endpoints and behavior
provide migration instructions
state the applicable transition or removal date
provide an overlap mechanism where technically and operationally practical

GraphJSON does not currently promise one universal deprecation window. The changelog entry for a change is the source of truth for its dates.

For a high-volume or business-critical integration, email hi@graphjson.com so the expected workload and change-notification path are known.

Build a resilient client#

Pin what you control#

Keep GraphJSON request construction in one shared module:

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

export async function logEvent(event: unknown, timestamp: number) {
  const response = await fetch(`${GRAPHJSON_API}/api/log`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      api_key: process.env.GRAPHJSON_API_KEY,
      collection: "product_events",
      json: JSON.stringify(event),
      timestamp
    }),
    signal: AbortSignal.timeout(10_000)
  });

  const body = await response.text();

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

A shared module makes timeouts, retries, endpoint changes, and redaction rules reviewable in one place.

Tolerate additive responses#

Read only the fields you need:

const body = await response.json();
const url = body.url;

if (typeof url !== "string") {
  throw new Error("GraphJSON response did not include a URL");
}

Do not reject a response because it contains an unfamiliar additional field.

Treat strings as opaque where documented#

Do not parse meaning from:

generated iframe URLs
query job IDs
dashboard share-link IDs
human-readable error messages

Store and return them as complete values.

Validate at your boundary#

GraphJSON accepts flexible JSON. Your producer should still validate the event contract before sending:

required event name
identifier types
timestamp units
money units and currency
schema version
forbidden fields

API compatibility does not protect a team from changing its own event meaning.

Deprecation checklist#

When a changelog entry affects your integration:

Identify every calling service and environment.
Add contract tests for old and new behavior.
Test with representative payloads.
Confirm retry behavior and error parsing.
Update dashboards or queries affected by a field change.
Deploy during the overlap window.
Monitor rejected requests and data quality.
Remove compatibility code after the stated date.

Changelog#

July 26, 2026 — OpenAPI and Postman contracts published#

Type: Additive developer tooling

GraphJSON published:

The machine-readable files cover the five endpoints already listed in the public API overview. No endpoint behavior or authentication requirement changed.

July 26, 2026 — compatibility policy established#

Type: Documentation and policy

This public compatibility policy and changelog were established. Earlier API history has not been reconstructed here.

No API behavior changed as part of this entry.

The current documented ingestion boundaries are:

40 requests per second per workspace
up to 50 events per bulk request
up to 10,000 serialized characters per event payload
whole Unix seconds for event timestamps

These values consolidate existing public API documentation. Internal load testing above the request guardrail is not a customer limit increase.

July 26, 2026 — canonical ingestion host clarified#

Type: Documentation correction

The canonical public ingestion host is:

https://api.graphjson.com

Examples using https://www.graphjson.com/api/log were corrected. Integrations should use the canonical API host.

Follow changes#

Review this page when upgrading an integration or investigating a behavior change. Until an automated subscription is available, business-critical customers should also maintain a support contact with GraphJSON.

See Errors and limits and Service behavior and operational expectations for current runtime boundaries.