JSONPath Query API¶
Overview¶
Queries JSON with a bounded JSONPath subset and returns all matched values as a JSON array.
Endpoint¶
POST https://api.apidatatools.com/json-path-query-api
Authentication¶
Include x-api-key: YOUR_API_KEY.
Input modes¶
Supports synchronous body mode and asynchronous url and file modes.
Headers¶
| Header | Required | Default | Description |
|---|---|---|---|
x-api-key | Yes | — | API key. |
x-source-type | No | body | body, url, or file. |
x-json-path | No | $ | JSONPath expression. |
Supported JSONPath syntax¶
- Root:
$ - Properties:
$.storeor$['store'] - Array indexes, including negative indexes:
$.items[0] - Wildcards:
$.items[*]and$.* - Recursive descent:
$..nameand$..*
Filters, slices, scripts, and unions are not supported.
Accepted file extensions¶
.txt, .json, and .log.
curl example¶
curl -X POST 'https://api.apidatatools.com/json-path-query-api' \\
-H 'x-api-key: YOUR_API_KEY' \\
-H 'x-json-path: $.users[*].name' \\
--data-raw '{"users":[{"name":"Ada"},{"name":"Linus"}]}'
Result¶
Returns a downloadable JSON array and output preview. A query can return at most 10,000 values.
URL and file mode requests¶
URL mode sends {"url":"https://example.com/input.json"} with x-source-type: url. File mode sends {"file":"S3_KEY_RETURNED_BY_THE_UPLOAD_WORKFLOW"} with x-source-type: file. Include x-json-path on the submission; it is stored with the async job.
curl --request POST \
--url https://api.apidatatools.com/json-path-query-api \
--header 'x-api-key: YOUR_API_KEY' \
--header 'x-source-type: url' \
--header 'x-json-path: $.users[*].name' \
--header 'Content-Type: application/json' \
--data '{"url":"https://example.com/input.json"}'
curl --request POST \
--url https://api.apidatatools.com/json-path-query-api \
--header 'x-api-key: YOUR_API_KEY' \
--header 'x-source-type: file' \
--header 'x-json-path: $.users[*].name' \
--header 'Content-Type: application/json' \
--data '{"file":"S3_KEY_RETURNED_BY_THE_UPLOAD_WORKFLOW"}'
Success responses¶
Body mode returns HTTP 200 with request_id, status, file, and preview. URL/file submissions return HTTP 202:
{"status":"accepted","job_id":"JOB_ID","status_url":"https://api.apidatatools.com/jobs/JOB_ID","request_id":"REQUEST_ID"}
Async job status¶
Poll GET https://api.apidatatools.com/jobs/JOB_ID with x-api-key. Queued/processing responses include message and retry_after; success includes result.file and result.preview; failure includes error.code, error.message, and error.details.
{"request_id":"REQUEST_ID","job_id":"JOB_ID","status":"queued","created_at":1730000000,"updated_at":1730000000,"message":"Your job is being processed.","retry_after":2}
Error handling¶
Errors use {"status":"error","error":"ERROR_CODE","request_id":"REQUEST_ID","details":{"message":"..."}}.
| HTTP status | Error codes |
|---|---|
400 | INVALID_SOURCE_TYPE, INVALID_BODY_ENCODING, EMPTY_BODY, INVALID_JSON_PATH, UNSUPPORTED_JSON_PATH, TOO_MANY_RESULTS, INVALID_JSON, INVALID_JSON_ENCODING, JSON_TOO_DEEP |
401 | UNAUTHORIZED |
404 | USER_NOT_FOUND, UNKNOWN_FUNCTION |
413 | PAYLOAD_TOO_LARGE |
429 | QUOTA_EXCEEDED, RATE_LIMITED |
500 | PLAN_NOT_FOUND, AUTH_ERROR, INTERNAL_ERROR |
Async submission errors include INVALID_BODY, URL/file validation errors, FILE_TOO_LARGE, CONFIG_ERROR, and PLAN_CONFIG_ERROR. Worker failures include INVALID_JOB, DOWNLOAD_FAILED, and UPLOAD_FAILED. Status errors include INVALID_JOB_ID, JOB_NOT_FOUND, FORBIDDEN, and DDB_ERROR.
Async notes¶
- Honor
retry_afterwhile polling. - Plan limits control body/file size, quotas, rates, and retention.
- Download URLs are temporary.