API overview

The GraphJSON API ingests timestamped JSON events and returns the data or embed URL behind a visualization.

Base URL#

https://api.graphjson.com

All documented endpoints use HTTPS and accept JSON POST requests.

Endpoints#

Download the OpenAPI 3.1 description or Postman collection for machine-readable request schemas and client tooling. See OpenAPI and client tools before committing generated code.

If you consume /api/visualize/data, use Data API response contracts for exact envelopes, row shapes, normalization, empty states, and runtime validation.

Authentication#

Put the workspace API key in the JSON body:

{
  "api_key": "your_api_key"
}

GraphJSON does not currently use a Bearer token header for these endpoints. See Authentication.

Request format#

Set:

Content-Type: application/json

Example:

curl --request POST \
  --url https://api.graphjson.com/api/log \
  --header 'Content-Type: application/json' \
  --data '{
    "api_key": "your_api_key",
    "collection": "product_events",
    "timestamp": 1785081600,
    "json": "{\"event\":\"signup_completed\",\"user_id\":\"usr_42\"}"
  }'

The logging API’s json field is itself a serialized JSON object. Query and visualization endpoints use normal nested request values.

Responses#

Responses are JSON unless an error path returns plain text. Always branch on the HTTP status before parsing or using the body:

const response = await fetch(url, options);
const text = await response.text();

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

const data = text ? JSON.parse(text) : null;

A 2xx response indicates success. Validation and authentication errors generally return 400; ingestion throttling returns 429; an internal ingestion failure can return 500.

See Errors and limits for handling guidance.

Use Service behavior and operational expectations for freshness, caching, query, backup, and availability boundaries. Review API compatibility and changelog before changing a production integration.

For a possible multi-surface incident, use Service status and incident communication.

Server-side use#

All API keys are secret and workspace-scoped. Call GraphJSON from your server, worker, or trusted build process.

Security: Never include api_key in a browser bundle. To embed a chart, let your server call the iframe endpoint and return only the generated URL.

A recommended workflow#

For data and visualization requests:

1. Build a working chart in the GraphJSON dashboard.
2. Select Export → As Data API Call or As Embed API Call.
3. Copy the generated request to server code.
4. Move the key into a secret environment variable.
5. Add response checks, timeouts, and bounded retries.

Starting from an exported payload reduces mistakes in graph type, filters, and customization fields.