The JQ API

Permanently delete only the JSON upload identified by upload_id; other uploads, filters, modules, and quota records are unaffected. Use after the final process_json query or when early removal is needed. Use get_upload to inspect availability first if uncertain; do not delete while the ID is still needed. Pass the exact secret ID returned by upload_json or REST POST /uploads, not a filename or URL. Anyone holding that ID can delete the upload; a UUID quota key is not an ownership credential. Returns success:true,deleted:true even if already deleted or expired, so retries are safe. Reusing a deleted ID for processing fails. Does not consume processing quota and remains available when that quota is exhausted. Invalid ID arguments are rejected; storage failure returns success:false,error,status:503.

Read the current caller’s shared daily REST/MCP quota without consuming a call or creating a usage record. Use before a batch of processing/upload calls or after quota exhaustion to learn when to retry. This does not inspect, process, upload, or delete JSON. Takes no arguments: the server uses the request IP, or the UUID bearer token configured in the MCP client Authorization header. Do not pass credentials as tool arguments. Free-tier results contain success, tier (anonymous or uuid), limit, used, remaining, and reset_at (next midnight UTC). Limits are 100 calls per IP or 1,000 per UUID. Uploads and jq processing share this counter; metadata checks, deletion, and discovery are free. Active prepaid access returns tier:paid, unlimited:true, expires_at, privacy:zero_application_query_logs, auto_renew:false, and null allowance/count fields because paid query activity is not recorded. remaining is zero after exhaustion; used counts attempted charged calls and can exceed the limit. This is a point-in-time snapshot, not a reservation for concurrent requests. Quota UUIDs do not authenticate an account or grant upload ownership. Database failure returns a tool error with success:false,error,status:503; no JSON or caller identifier is returned.

Inspect one upload’s availability, expiration, and byte size without reading its contents, running jq, or extending its lifetime. Use before reusing an older upload_id or to check whether deletion or expiration has made it unavailable. To read contents, use process_json with upload_id and filter ".". To remove it, use delete_upload. Pass the exact secret upload_id returned by upload_json or REST POST /uploads. No upload listing is exposed; anyone holding an ID can inspect that one upload. Returns success, available, status (available, missing, or expired), expires_at (UTC), expires_in_seconds, and size_bytes. Missing/deleted and expired uploads return available:false and size_bytes:null as a successful status check; expiration reports zero seconds. Does not consume processing quota or change stored data. Invalid IDs are rejected; a storage failure returns success:false,error,status:503.

Optional per-query x402 payment costs 0.005 native USDC on Base: tools/call params._meta["com.thejqapi/payment"]={mode:"query",idempotency_key:"fresh UUID"}; add signed _meta["x402/payment"] on retry. Keep the identical arguments and key. Active passes never incur this charge. Payment precedes execution; runtime/URL errors are chargeable. A settled payment permits three identical delivery attempts within 15 minutes, including the first; results are re-executed, never cached. Pending settlement is a tool error without execution: inspect GET /access/purchases/{idempotency_key} using the same bearer UUID without a second payment. Changed requests/retry exhaustion return 409 and expired delivery 410. Per-query privacy excludes payload logs and free counters but retains one billing receipt per logical query and temporary keyed retry data; it is not the pass’s zero-query-record mode. Requires an x402 client and explicit 0.005-USDC spending policy. Never put payment/credentials in arguments. Apply a jq filter and return JSON results; this does not create or modify uploads. Choose exactly one source: input for an available JSON value, url for a public HTTPS document, or upload_id to reuse stored JSON. For a single query, pass input or url directly; use upload_json first only when several queries should reuse one document. For example, filter .name extracts a field, keys inspects structure, and . reads the complete document, including an upload. To check upload availability or remaining quota without running jq, use get_upload or get_quota. Document limit 5 MiB; URL fetches allow three redirects and ten seconds, without caller credentials or private networks. Upload IDs expire 15 minutes after creation. Anyone holding an ID can query, inspect, or delete that upload. Runs real jq in isolated WebAssembly memory. Supply modules as options.modules filenames mapped to source on each call; they disappear afterward and need no separate management. Returns success, result, rawResult, results (every emitted jq value), stdout, jqVersion, executionTime, and optional stderr. Free-tier processing uses one shared daily REST/MCP quota call: 100 per IP or 1,000 per client-configured UUID bearer token, resetting at midnight UTC. Both free and paid keep JSON, filters, results, and source URLs out of application logs. Active 30-day passes additionally skip IP/UUID daily counters, query counts, and source analytics, with unlimited queries and zero application query logs. Expired paid UUIDs reject ordinary queries until renewed or explicitly paid per query, without free-tier tracking. Use get_quota to inspect active access. Minimal billing records, explicit uploads, public payments, and Cloudflare infrastructure boundaries are disclosed at https://thejqapi.com/privacy. jq failures return success:false and error; input failures may include status 400 (invalid), 404 (missing upload), 410 (expired), 413 (too large), 415 (unsupported data), 502/504 (URL failure/timeout), or 503 (storage unavailable). Quota exhaustion returns a tool error with remaining:0, reset_at, a structured upgrade offer linking pricing and browser checkout, and reset details in _meta.rateLimit. Use purchase_access only under an authorized spending policy; otherwise wait for reset.

Purchase or resume a prepaid access pass for the UUID configured in the MCP client Authorization header. The fixed price is 2 USDC for 30 days of unlimited jq queries and zero application query logs; each renewal is a separate purchase after expiration. Use only when paid access is wanted; use get_quota to inspect active access first. An active pass returns its status without charging again. Discovery and status checks are free. Expired paid UUIDs reject ordinary queries until renewed or explicitly paid per query and never fall back to tracked free access, even after old billing records are deleted. Browser wallet checkout and private MCP settings are available at https://thejqapi.com/access; ordinary MCP clients need no wallet after payment. Requires an x402-capable client with a funded wallet and an explicit spending policy allowing 2 USDC. The initial tool error contains standard x402 v2 PaymentRequired data. Retry with the signed payment in request _meta["x402/payment"], never in arguments. The optional purchase_id resumes an earlier order; keep the same order on retries. The UUID remains a secret bearer credential and must never be included in arguments. Returns active status or a purchase_id, settlement status, transaction receipt, and expires_at when activated. A pending settlement must be checked again without a new payment. Invalid input is 400, missing UUID 401, unavailable purchase 404, conflicting or expired order 409, and disabled/unavailable billing 503. Purchases are live with native USDC on Base mainnet (eip155:8453). The pass preserves 5 MiB document and 15-minute upload limits. Minimal billing/access records and explicitly requested uploads are retained separately. Payments are public onchain; Cloudflare infrastructure policies apply. GET https://thejqapi.com/pricing reports current availability.

Store one JSON document in private temporary storage for repeated process_json queries; this does not run a jq filter. Use when the same input will be queried more than once. For a single query, pass input or url directly to process_json instead. Provide exactly one of input or url, never both. A local file must be sent to REST POST /uploads by the client; this tool cannot read local paths. Maximum 5 MiB; URLs must be public HTTPS JSON on port 443, without credentials, private addresses, or custom headers. URL fetching is bounded to three redirects and ten seconds. Returns success:true, a secret upload_id, expires_at (UTC), and size_bytes. The ID is reusable for 15 minutes; uploads do not refresh expiration when queried. Uploads are immutable: create a new upload to change the JSON, then delete the old ID. Anyone holding the ID can inspect, query, or delete it. Use get_upload for metadata, process_json for contents or filtering, and delete_upload for early cleanup. Consumes one shared daily quota call on the free tier; active prepaid passes bypass that counter. Retrying creates another upload. No signup; a UUID bearer header selects the access tier but does not establish upload ownership. Failures return success:false and error, with status 400 for invalid input/URL/JSON, 413 for oversize data, 415 for unsupported content, 502/504 for URL failures, or 503 for storage failure. Exhausted quota returns a tool error with remaining:0, reset_at, and a structured upgrade offer linking pricing and checkout; inspect _meta.rateLimit for limit and reset.