Docs · HTTP
HTTP API
any language
Reference
Endpoint reference
Gateway Reference
Authenticated locker and file endpoints carry two headers: X-Nukez-Envelope and X-Nukez-Signature. The envelope binds method, path, body_sha256, receipt_id, locker_id, nonce, iat/exp, and the required ops array. POST bodies hash the exact bytes sent; authenticated GETs sign body_sha256 of empty bytes. See /docs/http/helpers for portable signers.
Discovery
| Method | Path | Auth | Description |
|---|---|---|---|
| GET | /.well-known/nukez.json | none | Service capabilities, supported networks, signed-envelope ops by endpoint, and real-world failure-mode hints. |
Storage payment (x402 v2)
| Method | Path | Auth | Description |
|---|---|---|---|
| POST | /v1/storage/request | none | Returns HTTP 402 with x402 v2 accepts[] (8 legs at present: Solana SOL/USDC/USDT/WETH and Monad USDC/USDT0/MON/WETH). Quote TTL is 300s. |
| POST | /v1/storage/confirm | X402-TX | Body carries pay_req_id, pay_network, and pay_asset for the SELECTED accepts[] leg. X402-TX header carries the on-chain tx signature. Returns receipt + receipt_id. |
Locker provisioning + record
| Method | Path | Auth | Description |
|---|---|---|---|
| POST | /v1/storage/signed_provision | X-Nukez-Envelope · locker:provision | Provisions the locker bound to the receipt. locker_id is deterministic — sha256(receipt_id).hex()[:12]. |
| GET | /v1/lockers/{locker_id}/record | X-Nukez-Envelope · locker:read | Cold-path locker ownership document (locker_record_v4) — owner_id, operator_ids, provider, bucket, path_prefix. |
| GET | /v1/storage/metadata/{locker_id} | X-Nukez-Envelope · locker:read | Locker metadata (locker_metadata_v1) including paid_amount, paid_raw, pay_asset, tx_hash, units, unit_price_usd. result_hash populates after attest. |
| POST | /v1/storage/refresh | X-Nukez-Envelope · locker:refresh | Refreshes the locker manifest with a fresh ts and returns the file_api block. |
Files
| Method | Path | Auth | Description |
|---|---|---|---|
| POST | /v1/lockers/{locker_id}/files | X-Nukez-Envelope · locker:write | Create a file entry. Returns upload_url, download_url, confirm_url. urls_expire_in_sec is 1800. |
| POST | /v1/lockers/{locker_id}/files/batch | X-Nukez-Envelope · locker:write | Create entries for multiple files in one signed envelope. Returns per-file upload_url + a single confirm_batch_url. |
| GET | /v1/lockers/{locker_id}/files | X-Nukez-Envelope · locker:list | List files in the locker. Authenticated GETs still sign body_sha256 of empty bytes. |
| GET | /v1/lockers/{locker_id}/files/{filename} | X-Nukez-Envelope · locker:read | Re-mint upload_url + download_url for an existing file (?ttl_min=30 default). |
| DELETE | /v1/lockers/{locker_id}/files/{filename} | X-Nukez-Envelope · locker:write | Tombstone the file in the manifest. |
| PUT | {upload_url} | URL token | Direct PUT to the GCS signed URL from create_file. Anything potentially over 30 MB needs the resolve-redirect pattern (Cloud Run hard 32 MB body cap). |
| GET | {download_url} | URL token | Direct GET from the GCS signed URL. Time-limited; for sharing prefer the receipt proxy below. |
| POST | /v1/files/confirm?receipt_id={rid}&filename={f} | URL token | Confirm a single file upload. Records size_bytes + content_hash. |
| POST | /v1/files/confirm-batch | URL token | Confirm a batch upload. Re-confirm individual files via /v1/files/confirm if a single member fails (UPLOAD_VERIFY_MISSING_AFTER_WRITE). |
| GET | /v1/r/{receipt_id}/f/{filename} | none | Public, stable receipt-based file proxy. 307-redirects to a fresh signed storage URL on every request — never expires, no GCS bucket-path leakage. |
Attestation + verification
| Method | Path | Auth | Description |
|---|---|---|---|
| POST | /v1/storage/attest?receipt_id={rid} | X-Nukez-Envelope · locker:attest | Signed-envelope attestation: computes merkle root over confirmed files and pushes the att_code to a Switchboard PullFeed on Solana. Async/retryable: status "computed" → "complete" once the on-chain push confirms. The gateway also auto-attests after every successful file confirm via Cloud Tasks, so explicit calls here are only needed to force a fresh anchor immediately or to receive a synchronous result. |
| GET | /v1/attest-code?receipt_id={rid} | none | Short numeric att_code derived from result_hash, plus switchboard_slot/switchboard_tx for the latest anchor. |
| GET | /v1/storage/merkle-proof?receipt_id={rid}&filename={f} | none | Per-file Merkle inclusion proof: leaf_hash, proof[] (sibling+position), merkle_root, tree_depth, file_count, switchboard anchor. |
| POST | /v1/storage/verify | none | Public verification snapshot. Body: {receipt_id}. On confirmed lockers the response carries the populated content_proof + on_chain_anchor (auto-reattest runs after every file confirm). Empty or pre-attest lockers return verified=false with an attestation_hint pointer. |
| GET | /v1/storage/verification-bundle?receipt_id={rid} | none | Self-contained portable proof: payment_proof + content_proof (merkle_root, files) + on_chain_anchor + merkle_algorithm + verify_yourself + verify_page_url. |
| GET | /specs/nukez-merkle-v1.json | none | Machine-readable canonical Merkle V1 specification for agents, auditors, SDKs, and external verifiers. |
| GET | /v1/receipts/{rid} | none | Stored receipt object with receipt_hash and full payment metadata. |
| GET | /v1/receipts/{rid}/verify | none | Server-recomputed receipt_hash for tamper-evidence cross-check. |