---
title: "Use this when you need to pull specific values out of a JSON document by JSONPath and getting the path exactly right on deeply nested or large structures matters."
method: POST
path: "/v1/query_json"
tags: ["data"]
---

# Use this when you need to pull specific values out of a JSON document by JSONPath and getting the path exactly right on deeply nested or large structures matters.

`POST /v1/query_json`

## Request

- Base URL: `https://api.clean.tools`
- URL: `https://api.clean.tools/v1/query_json`
- Auth: none declared

Use this when you need to pull specific values out of a JSON document by JSONPath and getting the path exactly right on deeply nested or large structures matters. Evaluates a JSONPath subset — $ (root), .name or ['name'] (child), [n] (index, negative allowed), [*] (wildcard), .. (recursive descent), and [start:end] (slice) — and returns every matching value in document order. Prefer this over hand-walking nested JSON, where it is easy to miscount array indices or miss a deep match. Filter (?()) and script (()) expressions are not supported and are rejected with a message naming the supported subset. Deterministic: same input, same output. Example: path "$.store.book[-1].title" over {"store":{"book":[{"title":"A"},{"title":"B"}]}} -> matches ["B"], count 1.

## Request body

- object
  - `json` string, required: The JSON document to query, as a string. Must parse as valid JSON (object, array, or primitive).
  - `path` string, required: JSONPath (subset). Supports $ root, .name / ['name'] child, [n] index (negative allowed), [*] wildcard, .. recursive descent, and [start:end] slice (optional :step). Filter (?()) and script (()) expressions are not supported. Example: $.items[*].id

## Response `200`

Structured tool result.

- object
  - `tool` string
  - `result` object
    - `path` string, required: Echo of the JSONPath that was evaluated.
    - `matches` unknown[], required: Every matching value in document order; items may be any JSON type (object, array, string, number, boolean, or null).
      - unknown
    - `count` integer, required: Number of matches (equals matches.length).
    - `truncated` boolean, required: True if the internal match cap was reached and further matches were dropped.

## Other responses

- `400`: Invalid input or the tool reported an error.
- `413`: Request body exceeds the 128 KB limit.
- `429`: Rate limit exceeded; the response carries Retry-After and RateLimit-* headers — honor them and add jitter.

---

[API](https://skmtc.dev/clean/apis/clean-tools-api.md) · [All operations](https://skmtc.dev/clean/apis/clean-tools-api/llms.txt) · [OpenAPI document](https://skmtc.dev/clean/apis/clean-tools-api/revisions/a24a01d2833c?raw)