API Reference
Format, Validate, and Transform JSON Data
Available Endpoints
Access JSONFlow’s processing engine via RESTful endpoints. All requests require a valid X-API-Key header and must be routed over HTTPS to api.jsonflow.dev/v1.
POST /format
Restructures raw JSON strings with configurable indentation, key sorting, and trailing newline enforcement. Supports minification and Prettier-style alignment for CI/CD pipelines.
POST /validate
Checks JSON syntax against RFC 8259 and optional JSON Schema drafts. Returns precise line/column offsets for malformed payloads and schema violations.
POST /diff
Computes structural differences between two JSON objects. Outputs a unified patch format highlighting added, removed, and modified nodes for audit trails.
POST /convert
Translates JSON payloads to YAML, XML, or CSV. Handles nested arrays and type coercion with explicit mapping rules for legacy system integration.
Parameters & Payloads
All endpoints accept a JSON body. Optional query strings override default behavior without altering the core payload.
Authentication Headers
X-API-Key (Required): 64-character alphanumeric token. Content-Type (Required): Must be set to application/json. Idempotency-Key (Optional): Prevents duplicate processing on network retries.
/format Options
indent (integer, default: 2): Spaces per nesting level. sort_keys (boolean, default: false): Alphabetical key ordering. strict_mode (boolean, default: true): Rejects trailing commas and single quotes.
/validate Options
schema_url (string): Remote or local JSON Schema reference. draft_version (string): Supports draft-07 or draft-2020-12. max_depth (integer, default: 50): Circuit-breaker for recursive structures.
/convert Options
target_format (string): yaml, xml, or csv. flatten_arrays (boolean, default: false): Serializes nested lists into delimited strings for CSV export.
Response Schemas
Successful requests return HTTP 200 with a standardized envelope. Processing time is capped at 3 seconds to prevent thread exhaustion.
Standard Envelope
Every response includes request_id (UUID v4), timestamp (ISO 8601), and status (success or error). The processed output resides in the data field, while metadata like character counts and nesting depth populate metrics.
/format Response
data.formatted_json (string): The cleaned payload. metrics.original_bytes (integer): Size before transformation. metrics.compression_ratio (float): Space savings when minifying.
/validate Response
data.is_valid (boolean): Pass/fail flag. data.violations (array): List of schema mismatches containing path, message, and severity. metrics.nodes_scanned (integer): Total objects/arrays traversed.
/diff Response
data.changes (array): Objects with op (add, remove, replace), path (JSON Pointer), and value. metrics.divergence_score (float): Percentage of structural alteration.
Error Handling
API errors follow RFC 7807 Problem Details format. Retry failed requests using exponential backoff with a maximum of 4 attempts.
400 Bad Request
Triggered by malformed JSON, missing required headers, or invalid query parameters. Response includes detail with the exact syntax offset and hint suggesting corrections.
401 Unauthorized
Returned when X-API-Key is missing, expired, or lacks scope for the requested tier. Check your dashboard at dashboard.jsonflow.dev/keys to rotate credentials.
429 Too Many Requests
Rate limits are enforced at 1,200 requests per minute for Standard plans and 10,000 for Enterprise. The Retry-After header specifies the exact cooldown window in seconds.
500 Internal Server Error
Indicates a transient failure in the parsing engine. Logs are automatically captured under your request_id. Contact support@jsonflow.dev with the trace ID for immediate investigation.