Quickstart Guide: 5 Minutes to Production

Prerequisites

Before you begin, make sure your environment meets these requirements. The entire setup takes under two minutes.

Validate & Transform Your First Payload

Three languages, three endpoints, one result. Pick the snippet that matches your stack and run it.

Python

Install the SDK with pip install jsonflow==2.4.1, then validate and normalize a payload in four lines:

import jsonflow

client = jsonflow.Client(api_key="jf_live_8xK2mPqR9vL4wN7tY")

result = client.validate_and_transform(
    payload={"user_id": 42891, "email": "a.chen@acme.io", "role": "admin"},
    schema_id="sch_user_profile_v3",
    transform="flatten.nested_objects"
)

print(result.valid)        # True
print(result.normalized)   # {"user_id":42891,"email":"a.chen@acme.io","role":"admin"}

Node.js

Add the package via npm install @jsonflow/node@2.4.1 and use the async/await API:

import { JSONFlow } from "@jsonflow/node";

const client = new JSONFlow({ apiKey: "jf_live_8xK2mPqR9vL4wN7tY" });

const result = await client.validateAndTransform({
  payload: { user_id: 42891, email: "a.chen@acme.io", role: "admin" },
  schemaId: "sch_user_profile_v3",
  transform: "flatten.nested_objects"
});

console.log(result.valid);      // true
console.log(result.normalized); // { user_id: 42891, email: "a.chen@acme.io", role: "admin" }

cURL

No SDK needed. Hit the REST endpoint directly — ideal for scripts, Makefile targets, and GitHub Actions:

curl -s -X POST https://api.jsonflow.dev/v2/validate \
  -H "Authorization: Bearer jf_live_8xK2mPqR9vL4wN7tY" \
  -H "Content-Type: application/json" \
  -d '{
    "payload": {"user_id": 42891, "email": "a.chen@acme.io", "role": "admin"},
    "schema_id": "sch_user_profile_v3",
    "transform": "flatten.nested_objects"
  }'

All three calls return a JSON object with valid (boolean), normalized (the cleaned payload), and errors (array, empty if valid). Average latency is 12 ms on the free tier.

Integrate Into Your CI/CD Pipeline

Hook JSONFlow into GitHub Actions, GitLab CI, or Bitbucket Pipelines. The example below gates a deployment on schema validation.

GitHub Actions

Add this step to your .github/workflows/ci.yml. It runs on every push to main and fails the build if any JSON fixture in test/fixtures/ violates the schema:

name: Validate JSON Fixtures
on: [push]
jobs:
  json-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install JSONFlow CLI
        run: npm install -g @jsonflow/cli@2.4.1
      - name: Validate all fixtures
        run: |
          for f in test/fixtures/*.json; do
            jsonflow validate "$f" --schema sch_user_profile_v3 \
              --strict --fail-on-error
          done
        env:
          JSONFLOW_API_KEY: ${{ secrets.JSONFLOW_API_KEY }}

GitLab CI

Drop this stage into .gitlab-ci.yml to validate payloads before Docker image builds:

stages:
  - validate
  - build

jsonflow-validate:
  stage: validate
  image: node:20-slim
  script:
    - npm install -g @jsonflow/cli@2.4.1
    - jsonflow validate test/fixtures/ --schema sch_user_profile_v3 --strict
  variables:
    JSONFLOW_API_KEY: $JSONFLOW_API_KEY

Webhook Notifications

If you want asynchronous validation (e.g., for large payloads over 2 MB), configure a webhook endpoint. JSONFlow posts a validation.completed event to your URL within 200 ms:

curl -s -X POST https://api.jsonflow.dev/v2/webhooks \
  -H "Authorization: Bearer jf_live_8xK2mPqR9vL4wN7tY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://ci.acme.io/hooks/jsonflow",
    "events": ["validation.completed", "validation.failed"],
    "secret": "whsec_a1b2c3d4e5f6g7h8"
  }'

The webhook payload includes schema_id, valid, error_count, and a signatures header for HMAC-SHA256 verification. See our signature verification guide for code samples in 6 languages.

Troubleshooting

Common issues and their fixes. If your problem isn't listed here, open a thread on Discord or email support@jsonflow.dev.