{
  "$schema": "https://docs.nukez.xyz/schemas/tools-v1.json",
  "schema_version": "1.1",
  "service": {
    "name": "Nukez",
    "base_url": "https://api.nukez.xyz",
    "discovery": "/.well-known/nukez.json",
    "openapi": "/openapi.json",
    "description": "Pay-once persistent storage with verifiable receipts + provider-opaque short URL byte transfer."
  },
  "usage_guidance": {
    "when_to_use": "Use Nukez for persistent storage over HTTP with cryptographic receipts. No cloud credentials needed — just pay with Solana or EVM (x402) and start storing.",
    "best_for": "Agent-driven file storage, cross-session persistence, verifiable data provenance, multi-chain payment workflows, and any scenario where you want receipts without managing infrastructure.",
    "agent_note": "This is HTTP-first: no SDK required. You can operate entirely via HTTP requests + Solana or EVM signing.",
    "critical_guardrails": [
      "If a valid receipt_id already exists in context, reuse it. Do not repurchase storage unless user explicitly requests a new purchase.",
      "In sandbox/proxied runtimes, prefer upload sessions and upload token flow instead of direct local-path uploads.",
      "When upload errors include details.recovery_hint and details.next_best_method, follow those fields directly."
    ]
  },
  "auth_reference": {
    "public": {
      "description": "No auth headers required.",
      "tools": [
        "nukez_request_storage",
        "nukez_confirm_storage",
        "nukez_get_receipt",
        "nukez_verify_receipt",
        "nukez_verify_storage",
        "nukez_get_attest_code"
      ]
    },
    "signed_envelope": {
      "description": "Request-bound Ed25519 signature using payer key.",
      "headers": {
        "X-Nukez-Envelope": "base64url(canonical_json(envelope))",
        "X-Nukez-Signature": "base58(ed25519_sign(envelope_bytes))"
      },
      "envelope_fields": [
        "v",
        "locker_id",
        "receipt_id",
        "nonce",
        "iat",
        "exp",
        "ops",
        "method",
        "path",
        "body_sha256"
      ],
      "see": "/docs/AUTH_SIGNED_ENVELOPE.md"
    },
    "signed_urls": {
      "description": "upload_url/download_url are provider-opaque short URLs (https://api.nukez.xyz/f/{token}) used for PUT/GET bytes.",
      "note": "If a short URL fails with 403/404, call GET /v1/lockers/{locker_id}/files/{filename} to refresh URLs. Verify token signatures with GET /v1/short-url/verify-key.",
      "verify_key": "/v1/short-url/verify-key",
      "format": "https://api.nukez.xyz/f/{ed25519_signed_token}"
    },
    "verification_spec": {
      "name": "nukez-merkle-v1",
      "schema_version": "1.0",
      "status": "normative",
      "canonical_doc": "https://docs.nukez.xyz/docs/verify/merkle-v1.md",
      "machine_readable": "https://docs.nukez.xyz/specs/nukez-merkle-v1.json",
      "summary": "Canonical Merkle / attestation spec for third-party verification. Covers leaf hashing, sort order, parent formula, odd-level duplication, result_hash, att_code, inclusion proof verification, Solana/Switchboard + Monad anchors, and a conformance test vector.",
      "important": "att_code is derived from result_hash, not merkle_root, and is NOT a security primitive. The authoritative values are result_hash, merkle_root, file entries, and on-chain anchors."
    }
  },
  "tools": [
    {
      "name": "nukez_request_storage",
      "description": "Start the x402 payment flow. IMPORTANT: this endpoint may return HTTP 402 with a JSON body that contains payment instructions. Treat HTTP 402 here as an expected 'payment challenge', not a failure. Provider can be selected via body.provider when enabled.",
      "when_to_call": "When you need to purchase/provision new storage units.",
      "input_schema": {
        "type": "object",
        "properties": {
          "units": {
            "type": "integer",
            "minimum": 1,
            "default": 1,
            "description": "Number of storage units to purchase."
          },
          "idempotency_key": {
            "type": "string",
            "description": "Optional idempotency key for safe retries (Idempotency-Key header)."
          },
          "existing_receipt_id": {
            "type": "string",
            "description": "Sandbox guardrail input. If provided with execution_mode='sandbox', the API blocks repurchase unless explicit_purchase=true."
          },
          "execution_mode": {
            "type": "string",
            "description": "Optional runtime hint. Use 'sandbox' for constrained app runtimes."
          },
          "explicit_purchase": {
            "type": "boolean",
            "description": "Set true only when the user explicitly requests buying new storage."
          },
          "provider": {
            "type": "string",
            "enum": [
              "gcs",
              "mongodb",
              "storj",
              "arweave",
              "filecoin",
              "firestore"
            ],
            "description": "Optional storage provider selection. If omitted, server default is used."
          },
          "pay_network": {
            "type": "string",
            "enum": [
              "solana-mainnet",
              "monad-mainnet"
            ],
            "description": "Optional. Network to pay on. If omitted, server default is used."
          },
          "pay_asset": {
            "type": "string",
            "enum": [
              "SOL",
              "USDC",
              "USDT",
              "USDT0",
              "WETH",
              "BETA",
              "MON"
            ],
            "default": "SOL",
            "description": "Optional. Payment asset. Default: SOL."
          }
        },
        "required": [
          "units"
        ]
      },
      "output_schema": {
        "type": "object",
        "properties": {
          "pay_req_id": {
            "type": "string"
          },
          "pay_to_address": {
            "type": "string"
          },
          "amount_sol": {
            "type": "number",
            "description": "Deprecated alias for amount when pay_asset=SOL. Prefer paid_amount."
          },
          "paid_amount": {
            "type": "string",
            "description": "Chain-agnostic human-readable payment amount."
          },
          "paid_raw": {
            "type": "string",
            "description": "Atomic units (lamports, wei, etc.)."
          },
          "pay_asset": {
            "type": "string",
            "description": "Payment asset used (SOL, USDC, USDT, USDT0, WETH, BETA, MON)."
          },
          "network": {
            "type": "string",
            "description": "Payment network (solana-mainnet, monad-mainnet)."
          },
          "amount_lamports": {
            "type": "integer"
          },
          "unit_price_usd": {
            "type": "number"
          },
          "total_usd": {
            "type": "number"
          },
          "sol_usd": {
            "type": "number"
          },
          "value": {}
        },
        "required": [
          "paid_amount",
          "network",
          "pay_req_id",
          "pay_to_address",
          "pay_asset",
          "value"
        ]
      },
      "http": {
        "method": "POST",
        "path": "/v1/storage/request",
        "content_type": "application/json",
        "headers": {
          "Idempotency-Key": "{idempotency_key} (optional)"
        },
        "query_parameters": {
          "pay_network": "Optional. Filter pricing by network.",
          "pay_asset": "Optional. Filter pricing by asset."
        },
        "expected_status": [
          402,
          200
        ]
      },
      "auth": "public",
      "next_step": "Pay to pay_to_address for paid_amount using the specified pay_asset on the specified network, then call nukez_confirm_storage."
    },
    {
      "name": "nukez_confirm_storage",
      "description": "Confirm payment and receive a permanent receipt_id. Preferred proof: send transaction signature/hash in the X402-TX header. X402-TX accepts both Solana signatures (base58, ~88 chars) and EVM transaction hashes (0x + 64 hex chars). Fallback for constrained clients: include tx_sig in the JSON body along with pay_req_id.",
      "when_to_call": "After sending payment to pay_to_address returned by nukez_request_storage.",
      "input_schema": {
        "type": "object",
        "properties": {
          "pay_req_id": {
            "type": "string"
          },
          "tx_sig": {
            "type": "string",
            "description": "Transaction signature (Solana base58, ~88 chars) or EVM transaction hash (0x + 64 hex chars)."
          }
        },
        "required": [
          "pay_req_id",
          "tx_sig"
        ],
        "additionalProperties": true
      },
      "output_schema": {
        "type": "object",
        "properties": {
          "ok": {
            "type": "boolean"
          },
          "receipt_id": {
            "type": "string"
          },
          "receipt": {
            "type": "object",
            "properties": {
              "paid_amount": {
                "type": "string",
                "description": "Chain-agnostic human-readable amount paid."
              },
              "paid_raw": {
                "type": "string",
                "description": "Atomic units (lamports, wei, etc.)."
              },
              "pay_asset": {
                "type": "string",
                "description": "Payment asset (SOL, USDC, USDT, USDT0, WETH, BETA, MON)."
              },
              "network": {
                "type": "string",
                "description": "Payment network."
              },
              "slot": {
                "type": "integer",
                "description": "Solana only, null for EVM."
              },
              "block_number": {
                "type": "integer",
                "description": "EVM only, null for Solana."
              }
            }
          },
          "idempotent": {
            "type": "boolean"
          },
          "value": {}
        },
        "required": [
          "ok",
          "receipt_id",
          "value"
        ]
      },
      "http": {
        "method": "POST",
        "path": "/v1/storage/confirm",
        "content_type": "application/json",
        "headers": {
          "X402-TX": "{tx_sig} (preferred; Solana base58 signature or EVM 0x-prefixed tx hash; optional if tx_sig is provided in JSON body)"
        },
        "expected_status": [
          200,
          402
        ]
      },
      "auth": "public",
      "error_handling": {
        "tx_not_found": "Transaction not yet propagated; retry with exponential backoff.",
        "payment_verification_failed": "Confirm tx paid enough; retry only if you suspect RPC lag."
      },
      "next_step": "Call nukez_signed_provision with receipt_id to create a locker."
    },
    {
      "name": "nukez_signed_provision",
      "description": "Provision a locker from a confirmed receipt. Returns locker_id and a manifest describing the file API surface. Requires signed envelope with ops ['locker:provision'].",
      "when_to_call": "Once per receipt_id (safe to retry).",
      "input_schema": {
        "type": "object",
        "properties": {
          "receipt_id": {
            "type": "string"
          },
          "tags": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Optional tags"
          },
          "value": {
            "$ref": "#/components/schemas/ProvisionRequest"
          },
          "signed_envelope": {
            "type": "string",
            "description": "Input used to populate an HTTP header."
          },
          "signed_envelope_signature": {
            "type": "string",
            "description": "Input used to populate an HTTP header."
          }
        },
        "required": [
          "receipt_id",
          "value"
        ]
      },
      "output_schema": {
        "type": "object",
        "properties": {
          "ok": {
            "type": "boolean"
          },
          "space": {
            "type": "object",
            "description": "Locker manifest (runtime affordances)",
            "additionalProperties": true
          },
          "value": {}
        },
        "required": [
          "ok",
          "space",
          "value"
        ]
      },
      "http": {
        "method": "POST",
        "path": "/v1/storage/signed_provision",
        "content_type": "application/json",
        "headers": {
          "X-Nukez-Envelope": "{signed_envelope}",
          "X-Nukez-Signature": "{signed_envelope_signature}"
        },
        "expected_status": [
          200
        ]
      },
      "auth": "signed_envelope",
      "required_ops": [
        "locker:provision"
      ],
      "next_step": "Use space.file_api paths (or the standard /v1/lockers/{locker_id}/files endpoints) to create/list/get/delete files."
    },
    {
      "name": "nukez_create_file",
      "description": "Create (or update) a file entry and mint time-limited short URLs for upload/download. Upload bytes via HTTP PUT to upload_url.",
      "when_to_call": "When you need to upload new bytes or update an existing file.",
      "input_schema": {
        "type": "object",
        "properties": {
          "locker_id": {
            "type": "string"
          },
          "filename": {
            "type": "string",
            "description": "Optional. If omitted, server generates a filename."
          },
          "content_type": {
            "type": "string",
            "description": "Optional MIME type. If provided, you MUST use the same Content-Type in the PUT to upload_url."
          },
          "ttl_min": {
            "type": "integer",
            "minimum": 1,
            "maximum": 60,
            "default": 30,
            "description": "Signed URL TTL in minutes."
          },
          "value": {
            "$ref": "#/components/schemas/CreateFileRequest"
          }
        },
        "required": [
          "locker_id",
          "value"
        ]
      },
      "output_schema": {
        "type": "object",
        "properties": {
          "locker_id": {
            "type": "string"
          },
          "filename": {
            "type": "string"
          },
          "upload_url": {
            "type": "string"
          },
          "download_url": {
            "type": "string"
          },
          "upload_headers": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            }
          },
          "urls_expire_in_sec": {
            "type": "integer"
          },
          "value": {}
        },
        "required": [
          "download_url",
          "filename",
          "locker_id",
          "upload_url",
          "value"
        ]
      },
      "http": {
        "method": "POST",
        "path": "/v1/lockers/{locker_id}/files",
        "content_type": "application/json",
        "expected_status": [
          200
        ]
      },
      "auth": "signed_envelope",
      "required_ops": [
        "locker:write"
      ],
      "next_step": "PUT raw bytes to upload_url, including any upload_headers, and matching Content-Type if content_type was locked."
    },
    {
      "name": "nukez_create_files_batch",
      "description": "Create multiple file entries and mint short upload/download URLs in one call.",
      "when_to_call": "When uploading multiple files (mixed MIME types) and you want one signed request to return all URLs.",
      "input_schema": {
        "type": "object",
        "properties": {
          "locker_id": {
            "type": "string"
          },
          "ttl_min": {
            "type": "integer",
            "minimum": 1,
            "maximum": 1440,
            "default": 30
          },
          "files": {
            "type": "array",
            "minItems": 1,
            "maxItems": 100,
            "items": {
              "type": "object",
              "properties": {
                "filename": {
                  "type": "string"
                },
                "content_type": {
                  "type": "string"
                },
                "expected_hash": {
                  "type": "string"
                }
              }
            }
          },
          "value": {
            "$ref": "#/components/schemas/BatchCreateFileRequest"
          }
        },
        "required": [
          "files",
          "locker_id",
          "value"
        ]
      },
      "output_schema": {
        "type": "object",
        "properties": {
          "locker_id": {
            "type": "string"
          },
          "file_count": {
            "type": "integer"
          },
          "urls_expire_in_sec": {
            "type": "integer"
          },
          "files": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "filename": {
                  "type": "string"
                },
                "upload_url": {
                  "type": "string"
                },
                "download_url": {
                  "type": "string"
                },
                "content_type": {
                  "type": "string"
                }
              },
              "required": [
                "filename",
                "upload_url",
                "download_url"
              ]
            }
          },
          "value": {}
        },
        "required": [
          "files",
          "locker_id",
          "value"
        ]
      },
      "http": {
        "method": "POST",
        "path": "/v1/lockers/{locker_id}/files/batch",
        "content_type": "application/json",
        "expected_status": [
          200
        ]
      },
      "auth": "signed_envelope",
      "required_ops": [
        "locker:write"
      ],
      "next_step": "Upload bytes to each returned upload_url (parallelizable), then confirm hashes via /v1/files/confirm-batch."
    },
    {
      "name": "nukez_get_file_urls",
      "description": "Mint fresh short URLs for an existing file (download and optionally upload).",
      "when_to_call": "When a previously minted short URL expired, or before downloading/updating an existing file.",
      "input_schema": {
        "type": "object",
        "properties": {
          "locker_id": {
            "type": "string"
          },
          "filename": {
            "type": "string"
          },
          "ttl_min": {
            "type": "integer",
            "minimum": 1,
            "maximum": 60,
            "default": 30
          }
        },
        "required": [
          "filename",
          "locker_id"
        ]
      },
      "output_schema": {
        "type": "object",
        "properties": {
          "locker_id": {
            "type": "string"
          },
          "filename": {
            "type": "string"
          },
          "upload_url": {
            "type": "string"
          },
          "download_url": {
            "type": "string"
          },
          "urls_expire_in_sec": {
            "type": "integer"
          },
          "value": {}
        },
        "required": [
          "download_url",
          "filename",
          "locker_id",
          "value"
        ]
      },
      "http": {
        "method": "GET",
        "path": "/v1/lockers/{locker_id}/files/{filename}?ttl_min={ttl_min}",
        "expected_status": [
          200
        ]
      },
      "auth": "signed_envelope",
      "required_ops": [
        "locker:read"
      ]
    },
    {
      "name": "nukez_list_files",
      "description": "List file metadata in a locker (filenames, content_type, timestamps).",
      "when_to_call": "When you need to discover what files exist in a locker.",
      "input_schema": {
        "type": "object",
        "properties": {
          "locker_id": {
            "type": "string"
          }
        },
        "required": [
          "locker_id"
        ]
      },
      "output_schema": {
        "type": "object",
        "properties": {
          "locker_id": {
            "type": "string"
          },
          "file_count": {
            "type": "integer"
          },
          "files": {
            "type": "array",
            "items": {
              "type": "object"
            }
          },
          "value": {}
        },
        "required": [
          "files",
          "locker_id",
          "value"
        ]
      },
      "http": {
        "method": "GET",
        "path": "/v1/lockers/{locker_id}/files",
        "expected_status": [
          200
        ]
      },
      "auth": "signed_envelope",
      "required_ops": [
        "locker:list"
      ]
    },
    {
      "name": "nukez_delete_file",
      "description": "Delete a file from a locker.",
      "when_to_call": "When you need to remove a stored object.",
      "input_schema": {
        "type": "object",
        "properties": {
          "locker_id": {
            "type": "string"
          },
          "filename": {
            "type": "string"
          }
        },
        "required": [
          "filename",
          "locker_id"
        ]
      },
      "output_schema": {
        "type": "object",
        "properties": {
          "ok": {
            "type": "boolean"
          },
          "locker_id": {
            "type": "string"
          },
          "filename": {
            "type": "string"
          },
          "value": {}
        },
        "required": [
          "value"
        ]
      },
      "http": {
        "method": "DELETE",
        "path": "/v1/lockers/{locker_id}/files/{filename}",
        "expected_status": [
          200
        ]
      },
      "auth": "signed_envelope",
      "required_ops": [
        "locker:write"
      ]
    },
    {
      "name": "nukez_get_receipt",
      "description": "Fetch a receipt by receipt_id.",
      "when_to_call": "When you need to audit or prove payment.",
      "input_schema": {
        "type": "object",
        "properties": {
          "receipt_id": {
            "type": "string"
          }
        },
        "required": [
          "receipt_id"
        ]
      },
      "output_schema": {
        "type": "object",
        "additionalProperties": true,
        "properties": {
          "paid_amount": {
            "type": "string",
            "description": "Chain-agnostic human-readable amount paid."
          },
          "paid_raw": {
            "type": "string",
            "description": "Atomic units (lamports, wei, etc.)."
          },
          "pay_asset": {
            "type": "string",
            "description": "Payment asset (SOL, USDC, USDT, USDT0, WETH, BETA, MON)."
          },
          "network": {
            "type": "string",
            "description": "Payment network."
          },
          "slot": {
            "type": "integer",
            "description": "Solana only, null for EVM."
          },
          "block_number": {
            "type": "integer",
            "description": "EVM only, null for Solana."
          },
          "value": {}
        },
        "required": [
          "value"
        ]
      },
      "http": {
        "method": "GET",
        "path": "/v1/receipts/{receipt_id}",
        "expected_status": [
          200
        ]
      },
      "auth": "public"
    },
    {
      "name": "nukez_verify_receipt",
      "description": "Verify a receipt signature / integrity.",
      "when_to_call": "When you need strong confidence the receipt is authentic.",
      "input_schema": {
        "type": "object",
        "properties": {
          "receipt_id": {
            "type": "string"
          }
        },
        "required": [
          "receipt_id"
        ]
      },
      "output_schema": {
        "type": "object",
        "additionalProperties": true,
        "properties": {
          "value": {}
        },
        "required": [
          "value"
        ]
      },
      "http": {
        "method": "GET",
        "path": "/v1/receipts/{receipt_id}/verify",
        "expected_status": [
          200
        ]
      },
      "auth": "public"
    },
    {
      "name": "nukez_verify_storage",
      "description": "Recompute stored object's sha256 and return a signed integrity certificate for the default payload.bin (legacy storage object).",
      "when_to_call": "When you need verifiable integrity for legacy payload.bin workflows.",
      "input_schema": {
        "type": "object",
        "properties": {
          "receipt_id": {
            "type": "string"
          },
          "value": {
            "title": "Payload"
          }
        },
        "required": [
          "receipt_id",
          "value"
        ]
      },
      "output_schema": {
        "type": "object",
        "additionalProperties": true,
        "properties": {
          "received_amount": {
            "type": "string",
            "description": "Chain-agnostic human-readable amount received."
          },
          "received_raw": {
            "type": "string",
            "description": "Atomic units received (lamports, wei, etc.)."
          },
          "pay_asset": {
            "type": "string",
            "description": "Payment asset verified (SOL, USDC, USDT, USDT0, WETH, BETA, MON)."
          },
          "value": {}
        },
        "required": [
          "value"
        ]
      },
      "http": {
        "method": "POST",
        "path": "/v1/storage/verify",
        "content_type": "application/json",
        "expected_status": [
          200
        ]
      },
      "auth": "public"
    },
    {
      "name": "nukez_get_attest_code",
      "description": "Get an attestation code derived from the stored result_hash. If missing, run nukez_verify_storage first.",
      "when_to_call": "After verify_storage, or if the receipt already has a result_hash.",
      "input_schema": {
        "type": "object",
        "properties": {
          "receipt_id": {
            "type": "string"
          }
        },
        "required": [
          "receipt_id"
        ]
      },
      "output_schema": {
        "type": "object",
        "properties": {
          "receipt_id": {
            "type": "string"
          },
          "result_hash": {
            "type": "string"
          },
          "att_code": {
            "type": "string"
          },
          "value": {}
        },
        "required": [
          "value"
        ]
      },
      "http": {
        "method": "GET",
        "path": "/v1/attest-code?receipt_id={receipt_id}",
        "expected_status": [
          200,
          400
        ]
      },
      "auth": "public"
    },
    {
      "name": "nukez_start_upload_session",
      "description": "Start a sandbox upload session and mint a session-scoped upload token. Use this for app-sandbox uploads where direct file paths are restricted.",
      "when_to_call": "When uploading attachments from sandboxed runtimes and you already have locker_id + receipt_id.",
      "input_schema": {
        "type": "object",
        "properties": {
          "locker_id": {
            "type": "string"
          },
          "receipt_id": {
            "type": "string"
          },
          "files": {
            "type": "array",
            "minItems": 1,
            "maxItems": 100,
            "items": {
              "type": "object",
              "properties": {
                "filename": {
                  "type": "string"
                },
                "content_type": {
                  "type": "string"
                },
                "expected_size_bytes": {
                  "type": "integer"
                },
                "expected_sha256": {
                  "type": "string"
                }
              },
              "required": [
                "filename"
              ]
            }
          },
          "upload_token_ttl_sec": {
            "type": "integer",
            "minimum": 60,
            "maximum": 86400
          }
        },
        "required": [
          "locker_id",
          "receipt_id",
          "files"
        ]
      },
      "output_schema": {
        "type": "object",
        "properties": {
          "session_id": {
            "type": "string"
          },
          "upload_token": {
            "type": "string"
          },
          "endpoints": {
            "type": "object"
          },
          "viewer_url": {
            "type": "string"
          },
          "ui": {
            "type": "object"
          },
          "contract": {
            "type": "object"
          }
        },
        "required": [
          "session_id",
          "upload_token",
          "viewer_url",
          "ui",
          "contract"
        ]
      },
      "http": {
        "method": "POST",
        "path": "/v1/lockers/{locker_id}/upload-sessions",
        "content_type": "application/json",
        "expected_status": [
          200
        ]
      },
      "auth": "signed_envelope",
      "required_ops": [
        "locker:write"
      ],
      "next_step": "Upload bytes using nukez_append_upload_session_part, then call nukez_finalize_upload_session."
    },
    {
      "name": "nukez_append_upload_session_part",
      "description": "Append one base64 chunk to a file inside an upload session.",
      "when_to_call": "After nukez_start_upload_session for each file chunk.",
      "input_schema": {
        "type": "object",
        "properties": {
          "session_id": {
            "type": "string"
          },
          "file_id": {
            "type": "string"
          },
          "part_no": {
            "type": "integer",
            "minimum": 0
          },
          "payload_b64": {
            "type": "string"
          },
          "is_last": {
            "type": "boolean",
            "default": false
          }
        },
        "required": [
          "session_id",
          "file_id",
          "part_no",
          "payload_b64"
        ]
      },
      "output_schema": {
        "type": "object",
        "properties": {
          "session_id": {
            "type": "string"
          },
          "file_id": {
            "type": "string"
          },
          "bytes_received": {
            "type": "integer"
          },
          "part_count": {
            "type": "integer"
          }
        },
        "required": [
          "session_id",
          "file_id"
        ]
      },
      "http": {
        "method": "POST",
        "path": "/v1/upload-sessions/{session_id}/files/{file_id}/parts",
        "content_type": "application/json",
        "expected_status": [
          200
        ]
      },
      "auth": "upload_session_token_or_signed_envelope"
    },
    {
      "name": "nukez_get_upload_session",
      "description": "Get upload session status and per-file state. Returns viewer_url + UI contract.",
      "when_to_call": "To poll upload progress until terminal status.",
      "input_schema": {
        "type": "object",
        "properties": {
          "session_id": {
            "type": "string"
          }
        },
        "required": [
          "session_id"
        ]
      },
      "output_schema": {
        "type": "object",
        "properties": {
          "session_id": {
            "type": "string"
          },
          "status": {
            "type": "string"
          },
          "terminal": {
            "type": "boolean"
          },
          "viewer_url": {
            "type": "string"
          },
          "ui": {
            "type": "object"
          },
          "contract": {
            "type": "object"
          }
        },
        "required": [
          "session_id",
          "status",
          "terminal",
          "viewer_url",
          "ui",
          "contract"
        ]
      },
      "http": {
        "method": "GET",
        "path": "/v1/upload-sessions/{session_id}",
        "expected_status": [
          200
        ]
      },
      "auth": "upload_session_token_or_signed_envelope"
    },
    {
      "name": "nukez_finalize_upload_session",
      "description": "Finalize an upload session (assemble parts, verify upload integrity, and emit viewer contract).",
      "when_to_call": "After all chunks have been appended for all files.",
      "input_schema": {
        "type": "object",
        "properties": {
          "session_id": {
            "type": "string"
          },
          "file_ids": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        },
        "required": [
          "session_id"
        ]
      },
      "output_schema": {
        "type": "object",
        "properties": {
          "session_id": {
            "type": "string"
          },
          "status": {
            "type": "string"
          },
          "terminal": {
            "type": "boolean"
          },
          "result": {
            "type": "object"
          },
          "viewer_url": {
            "type": "string"
          },
          "ui": {
            "type": "object"
          },
          "contract": {
            "type": "object"
          }
        },
        "required": [
          "session_id",
          "status",
          "terminal",
          "viewer_url",
          "ui",
          "contract"
        ]
      },
      "http": {
        "method": "POST",
        "path": "/v1/upload-sessions/{session_id}/finalize",
        "content_type": "application/json",
        "expected_status": [
          200
        ]
      },
      "auth": "upload_session_token_or_signed_envelope"
    },
    {
      "name": "nukez_get_viewer",
      "description": "Return a viewer-first payload for locker or file display. Always returns viewer_url + button contract.",
      "when_to_call": "When the user asks to view locker contents or a specific file.",
      "input_schema": {
        "type": "object",
        "properties": {
          "locker_id": {
            "type": "string"
          },
          "receipt_id": {
            "type": "string"
          },
          "filename": {
            "type": "string"
          }
        },
        "required": [
          "locker_id"
        ]
      },
      "output_schema": {
        "type": "object",
        "properties": {
          "viewer_url": {
            "type": "string"
          },
          "ui": {
            "type": "object"
          },
          "contract": {
            "type": "object"
          }
        },
        "required": [
          "viewer_url",
          "ui",
          "contract"
        ]
      },
      "http": {
        "method": "GET",
        "path": "/v1/lockers/{locker_id}/viewer",
        "expected_status": [
          200
        ]
      },
      "auth": "signed_envelope",
      "required_ops": [
        "locker:read"
      ]
    },
    {
      "name": "nukez_get_short_url_verify_key",
      "description": "Get the Ed25519 public key used to verify short URL tokens.",
      "when_to_call": "When independently validating that a short URL token was issued by Nukez.",
      "input_schema": {
        "type": "object",
        "properties": {}
      },
      "http": {
        "method": "GET",
        "path": "/v1/short-url/verify-key",
        "expected_status": [
          200
        ]
      },
      "auth": "public",
      "output_hints": [
        "verify_key_hex",
        "algorithm"
      ]
    }
  ],
  "contract_notes": [
    "HTTP 402 from /v1/storage/request is an expected payment challenge.",
    "Do not POST bytes to the API; always use upload_url/download_url short URLs.",
    "For signed_envelope: body_sha256 must match SHA256 of the exact bytes you send on the wire (canonical JSON)."
  ],
  "error_recovery": {
    "signed_url_expired": "Call nukez_get_file_urls to mint new URLs.",
    "tx_not_found": "Retry confirm_storage with exponential backoff."
  }
}