Skip to content

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: $.store or $['store']
  • Array indexes, including negative indexes: $.items[0]
  • Wildcards: $.items[*] and $.*
  • Recursive descent: $..name and $..*

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_after while polling.
  • Plan limits control body/file size, quotas, rates, and retention.
  • Download URLs are temporary.