Name: JSON Validator API: Format, Convert and Diff JSON
Brand: spacecmd-kits
SKU: api-spacecmd-kits-json-tool
Availability: InStock
Author: API Market

# JSON Tool API

## Overview

The JSON Tool API runs common JSON jobs in a single call: validate, pretty-print, minify, convert to CSV, YAML or TOON, and compare two documents. It has 2 endpoints that share the same set of operations, chosen with the `op` query parameter. `POST /v1/json` takes the JSON document in the request body and is the one to use for real payloads. `GET /v1/json-get` takes the JSON URL-encoded in the `input` query parameter, which is handy for small inputs from a browser, a shell or an agent tool call. The operations are `validate`, `format` (with an `indent` of 0 to 8), `minify`, `to-csv`, `to-yaml`, `to-toon` and `diff`. According to the provider there is also a `from-csv` operation that converts CSV back to JSON; we have not tested it.

It is built for developers and AI agent builders who need to check or reshape JSON without writing that code themselves: pipelines that turn JSON records into CSV or YAML, tools that clean up model output before using it, and anyone who wants to shrink JSON before putting it in an LLM prompt with the token-compact TOON format. Every response is a small JSON object that starts with the `op` that ran. Converting operations return the result as a string in `output`; `validate` returns `valid`, the detected `type` and the size in `bytes`, or an `error` message when the JSON does not parse; `diff` returns `equal`, a `changes` count and a list of changes with `op`, `path` and values.

## Features

*   **2 endpoints**: `POST /v1/json` for JSON in the request body and `GET /v1/json-get` for small URL-encoded inputs. Both accept the same operations.
*   **7 tested operations**: `validate`, `format`, `minify`, `to-csv`, `to-yaml`, `to-toon` and `diff`. The provider also lists `from-csv`, which we have not tested.
*   **Simple inputs**: One `op` query parameter plus your JSON. `format` takes an optional `indent` from 0 to 8, and `diff` takes a body of the form `{"a": ..., "b": ...}`.
*   **Validation with error messages**: Invalid JSON returns `200` with `valid: false` and an `error` message that quotes the offending text, so you can show it to a user or send it back to a model.
*   **Format conversion**: JSON arrays of objects become CSV with a header row, and any JSON document can be converted to YAML.
*   **TOON output for LLMs**: `to-toon` re-encodes JSON in the compact TOON format and reports the character count before and after (`chars_json`, `chars_toon`). In our test a 54-character JSON document became 33 characters.
*   **Structural diff**: `diff` compares two documents and lists each change as a `replace`, `add` or similar operation with a JSON path.
*   **Processing method**: The JSON you send is processed directly by the API and the result is returned in the same response. Nothing needs to be uploaded or stored first.
*   **Rate limit**: 10 requests per second on the pay-as-you-go plan.

## Use Cases

*   **Checking model output**: Validate JSON produced by an LLM before parsing it, and feed the `error` message back to the model when it fails.
*   **Cutting prompt size**: Convert JSON data to TOON before placing it in a prompt to use fewer characters.
*   **Data export**: Turn an array of JSON records into CSV for spreadsheets or reporting tools.
*   **Config generation**: Convert JSON settings to YAML for configuration files and documentation.
*   **Change detection**: Diff two versions of a JSON document, such as an API response or a config file, to see exactly which fields changed.
*   **Pretty-printing and compacting**: Format JSON for logs and code reviews, or minify it for transport and storage.

## API Documentation

### Base URL

All requests go through the API.market gateway at this base URL:

```
https://prod.api.market/api/v1/spacecmd-kits/json-tool
```

### Authentication

Every request needs your API.market key in the `x-api-market-key` header:

```
x-api-market-key: YOUR_API_KEY
```

Replace `YOUR_API_KEY` with your actual API key.

### Endpoints

#### 1. Run a JSON operation (request body)

Runs one operation on the JSON document in the request body and returns the result. The response always includes `op`; the other fields depend on the operation, as shown in the examples below.

**Method:** `POST`

**Endpoint:** `/v1/json`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| `op` | query | The operation to run: `validate`, `format`, `minify`, `to-csv`, `from-csv`, `to-yaml`, `to-toon` or `diff`. | string | Yes | - | - |
| `indent` | query | Number of spaces per indent level. Used by `format` only. | string | No | - | 8 |
| (JSON document) | body | The JSON to process. Any JSON value is accepted; `to-csv` expects an array of objects. Send it with `Content-Type: application/json`. | object or array | Yes | - | - |
| `a` | body | For `diff` only: the first document to compare. | any | Yes, for `diff` | - | - |
| `b` | body | For `diff` only: the second document to compare. | any | Yes, for `diff` | - | - |

**Example Request:**

```bash
curl -X POST "https://prod.api.market/api/v1/spacecmd-kits/json-tool/v1/json?op=validate" \
  -H "x-api-market-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"users":[{"id":1,"name":"Ann"},{"id":2,"name":"Bo"}]}'
```

**Example Response (200 OK):**

```json
{
  "op": "validate",
  "valid": true,
  "type": "object",
  "bytes": 54
}
```

**Example Request (invalid JSON):**

```bash
curl -X POST "https://prod.api.market/api/v1/spacecmd-kits/json-tool/v1/json?op=validate" \
  -H "x-api-market-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data-raw $'{"a":1,\n "b": [1,2,}'
```

**Example Response (200 OK):**

```json
{
  "op": "validate",
  "valid": false,
  "error": "Unexpected token '}', \"{\"a\":1,\n \"b\": [1,2,}\" is not valid JSON",
  "line": null,
  "column": null,
  "context": null
}
```

The response has `line`, `column` and `context` fields, but they came back `null` in our test. Use the `error` message to report the problem.

**Example Request (format with a 2-space indent):**

```bash
curl -X POST "https://prod.api.market/api/v1/spacecmd-kits/json-tool/v1/json?op=format&indent=2" \
  -H "x-api-market-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"users":[{"id":1,"name":"Ann"},{"id":2,"name":"Bo"}]}'
```

**Example Response (200 OK):**

```json
{
  "op": "format",
  "output": "{\n  \"users\": [\n    {\n      \"id\": 1,\n      \"name\": \"Ann\"\n    },\n    {\n      \"id\": 2,\n      \"name\": \"Bo\"\n    }\n  ]\n}"
}
```

**Example Request (minify):**

```bash
curl -X POST "https://prod.api.market/api/v1/spacecmd-kits/json-tool/v1/json?op=minify" \
  -H "x-api-market-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"users":[{"id":1,"name":"Ann"},{"id":2,"name":"Bo"}]}'
```

**Example Response (200 OK):**

```json
{
  "op": "minify",
  "output": "{\"users\":[{\"id\":1,\"name\":\"Ann\"},{\"id\":2,\"name\":\"Bo\"}]}",
  "bytes_before": 54,
  "bytes_after": 54
}
```

The input in this example was already compact, so `bytes_before` and `bytes_after` are equal. See the GET example below for a minify that removes whitespace.

**Example Request (to-yaml):**

```bash
curl -X POST "https://prod.api.market/api/v1/spacecmd-kits/json-tool/v1/json?op=to-yaml" \
  -H "x-api-market-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"users":[{"id":1,"name":"Ann"},{"id":2,"name":"Bo"}]}'
```

**Example Response (200 OK):**

```json
{
  "op": "to-yaml",
  "output": "users:\n  - id: 1\n    name: Ann\n  - id: 2\n    name: Bo\n"
}
```

**Example Request (to-toon):**

```bash
curl -X POST "https://prod.api.market/api/v1/spacecmd-kits/json-tool/v1/json?op=to-toon" \
  -H "x-api-market-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"users":[{"id":1,"name":"Ann"},{"id":2,"name":"Bo"}]}'
```

**Example Response (200 OK):**

```json
{
  "op": "to-toon",
  "output": "users[2]{id,name}:\n  1,Ann\n  2,Bo",
  "chars_json": 54,
  "chars_toon": 33
}
```

**Example Request (to-csv):**

```bash
curl -X POST "https://prod.api.market/api/v1/spacecmd-kits/json-tool/v1/json?op=to-csv" \
  -H "x-api-market-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '[{"id":1,"name":"Ann"},{"id":2,"name":"Bo"}]'
```

**Example Response (200 OK):**

```json
{
  "op": "to-csv",
  "output": "id,name\n1,Ann\n2,Bo"
}
```

**Example Request (diff):**

```bash
curl -X POST "https://prod.api.market/api/v1/spacecmd-kits/json-tool/v1/json?op=diff" \
  -H "x-api-market-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"a":{"x":1,"y":2},"b":{"x":1,"y":3,"z":4}}'
```

**Example Response (200 OK):**

```json
{
  "op": "diff",
  "equal": false,
  "changes": 2,
  "diff": [
    {
      "op": "replace",
      "path": "/y",
      "from": 2,
      "value": 3
    },
    {
      "op": "add",
      "path": "/z",
      "value": 4
    }
  ]
}
```

Each entry in `diff` describes how to get from `a` to `b`: `path` points at the field, `from` holds the old value for a replacement, and `value` holds the new value.

#### 2. Run a JSON operation (query string)

Runs the same operations as `POST /v1/json`, with the JSON passed URL-encoded in the `input` query parameter. Use it for small inputs, since the whole document has to fit in the URL.

**Method:** `GET`

**Endpoint:** `/v1/json-get`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| `op` | query | The operation to run: `validate`, `format`, `minify`, `to-csv`, `from-csv`, `to-yaml`, `to-toon` or `diff`. | string | Yes | - | - |
| `input` | query | The JSON text to process, URL-encoded. | string | Yes | - | - |

**Example Request:**

```bash
curl -X GET "https://prod.api.market/api/v1/spacecmd-kits/json-tool/v1/json-get?op=minify&input=%7B%20%22a%22%20%3A%201%20%2C%20%22b%22%20%3A%20%5B%201%20%2C%202%20%5D%20%7D" \
  -H "x-api-market-key: YOUR_API_KEY"
```

**Example Response (200 OK):**

```json
{
  "op": "minify",
  "output": "{\"a\":1,\"b\":[1,2]}",
  "bytes_before": 29,
  "bytes_after": 17
}
```

The `input` here is `{ "a" : 1 , "b" : [ 1 , 2 ] }` URL-encoded. Minifying it took the size from 29 bytes to 17.

## Status Codes

| Code | Status | Description |
|---|---|---|
| 200 | OK | The operation ran. This includes `validate` on invalid JSON, which returns `valid: false` with an `error` message. |
| 400 | Bad Request | The input was rejected, for example a missing or unknown `op`, or a missing `input` on the GET endpoint. |
| 401 | Unauthorized | The `x-api-market-key` value is invalid or expired. |
| 403 | Forbidden | Your subscription does not include this endpoint. |
| 404 | Not Found | The path does not exist. Check that you are calling `/v1/json` or `/v1/json-get` under the base URL. |
| 429 | Too Many Requests | You went over 10 requests per second, or your account has reached a usage limit. |
| 500 | Internal Server Error | Something failed while processing the request. Retry after a short delay. |

## Rate Limits

The pay-as-you-go plan allows 10 requests per second. There is no subscription and no monthly quota: each call is billed at $0.002 from your API.market wallet, whichever operation you run. Requests above the per-second limit return `429 Too Many Requests`. Back off before retrying and honour any `Retry-After` header. In our tests most calls answered in about 0.7 to 0.9 seconds, and the first call took about 1.1 seconds.

## FAQ

**Which endpoint should I use, POST or GET?**

Use `POST /v1/json` for anything beyond a few fields: the JSON goes in the body and is not limited by URL length. `GET /v1/json-get` runs the same operations with URL-encoded JSON in `input`, which suits quick checks from a browser, a shell or an agent tool that can only make GET requests.

**Does validation tell me the line and column of an error?**

Do not rely on it. The response includes `line`, `column` and `context` fields, but in our test with invalid JSON they were all `null`. The `error` message is filled in and quotes the text that failed to parse.

**What is TOON and why would I use it?**

TOON is a compact text encoding of JSON data that drops repeated keys and most punctuation, for example `users[2]{id,name}:` followed by one line per record. It is meant for putting structured data in LLM prompts with fewer characters. The response reports `chars_json` and `chars_toon` so you can see the saving for your own data.

**What shape does `to-csv` expect?**

An array of objects. The keys of the objects become the CSV header row, and each object becomes one row. In our test `[{"id":1,"name":"Ann"},{"id":2,"name":"Bo"}]` became `id,name`, `1,Ann`, `2,Bo`.

**How do I compare two JSON documents?**

Call `op=diff` with a body of `{"a": <first document>, "b": <second document>}`. The response says whether they are `equal`, how many `changes` there are, and lists each change with its `op` (such as `replace` or `add`), the JSON `path`, and the old and new values.

**Can I convert CSV to JSON?**

The provider lists a `from-csv` operation for this. We have not tested it, so check the result on a sample before relying on it.

**How much does it cost?**

$0.002 per call on the pay-as-you-go plan, billed from your API.market wallet. There is no subscription or minimum, and every operation costs the same. You only need your `x-api-market-key`.

## Contact Us

If you have any questions or need assistance, you can reach out to us through the embedded chat on the bottom right corner of the page or send an email to hello@magicapi.com.


JSON validator API that also formats, minifies, diffs and converts JSON to CSV, YAML or TOON, returning the result or a clear error message in one call.