openapi: 3.1.0
info:
  title: Nukez — Permissionless Storage for Autonomous Agents
  version: 1.0.0
servers:
- url: https://api.nukez.xyz
components:
  schemas:
    AttestRequest:
      properties:
        receipt_id:
          type: string
          title: Receipt Id
        push:
          type: boolean
          title: Push
          default: false
      type: object
      required:
      - receipt_id
      title: AttestRequest
    BatchCreateFileItem:
      properties:
        filename:
          anyOf:
          - type: string
            maxLength: 255
            minLength: 1
          - type: 'null'
          title: Filename
        content_type:
          anyOf:
          - type: string
          - type: 'null'
          title: Content Type
        expected_hash:
          anyOf:
          - type: string
            maxLength: 128
            minLength: 1
          - type: 'null'
          title: Expected Hash
          description: Optional sha256 precommit hash (with or without 'sha256:' prefix)
      type: object
      title: BatchCreateFileItem
      description: Single file spec for batch URL creation.
    BatchCreateFileRequest:
      properties:
        files:
          items:
            $ref: '#/components/schemas/BatchCreateFileItem'
          type: array
          maxItems: 100
          minItems: 1
          title: Files
          description: Files to create and mint upload/download URLs for
        ttl_min:
          anyOf:
          - type: integer
            maximum: 1440.0
            minimum: 1.0
          - type: 'null'
          title: Ttl Min
          description: 'Signed URL lifetime in minutes (default: 30)'
          default: 30
      type: object
      required:
      - files
      title: BatchCreateFileRequest
      description: Request body for batch create_file operation.
    BatchUrlsRequest:
      properties:
        filenames:
          items:
            type: string
          type: array
          maxItems: 100
          minItems: 1
          title: Filenames
          description: List of filenames to generate download URLs for
        ttl_min:
          anyOf:
          - type: integer
            maximum: 1440.0
            minimum: 1.0
          - type: 'null'
          title: Ttl Min
          description: 'Signed URL lifetime in minutes (default: 30)'
          default: 30
      type: object
      required:
      - filenames
      title: BatchUrlsRequest
      description: Request body for batch download URL generation.
    CreateFileRequest:
      properties:
        filename:
          anyOf:
          - type: string
            maxLength: 255
            minLength: 1
          - type: 'null'
          title: Filename
        content_type:
          anyOf:
          - type: string
          - type: 'null'
          title: Content Type
        ttl_min:
          anyOf:
          - type: integer
            maximum: 1440.0
            minimum: 1.0
          - type: 'null'
          title: Ttl Min
      type: object
      title: CreateFileRequest
      description: "Request body for create_file.\n\nNotes:\n  - filename is optional (server can auto-generate).\n  - ttl_min controls the short URL lifetime."
    FinalizeUploadCreateRequest:
      properties:
        receipt_id:
          type: string
          minLength: 1
          title: Receipt Id
          description: Receipt ID bound to the locker
        filenames:
          items:
            type: string
          type: array
          maxItems: 1000
          minItems: 1
          title: Filenames
          description: Filenames to confirm and finalize in one async job
        auto_attest:
          type: boolean
          title: Auto Attest
          description: If true, run attestation after confirm-batch completes
          default: false
        attest_sync:
          type: boolean
          title: Attest Sync
          description: Reserved for compatibility; currently attestation runs synchronously inside the worker
          default: false
        push_attestation:
          type: boolean
          title: Push Attestation
          description: If true and auto_attest=true, push attestation on-chain
          default: false
        run_inline:
          type: boolean
          title: Run Inline
          description: Run job immediately in request thread (debug/dev only)
          default: false
      type: object
      required:
      - receipt_id
      - filenames
      title: FinalizeUploadCreateRequest
    FinalizeUploadJobRequest:
      properties:
        job_id:
          type: string
          title: Job Id
      type: object
      required:
      - job_id
      title: FinalizeUploadJobRequest
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ProvisionRequest:
      properties:
        receipt_id:
          type: string
          minLength: 1
          title: Receipt Id
        tags:
          items:
            type: string
          type: array
          title: Tags
      type: object
      required:
      - receipt_id
      title: ProvisionRequest
    RefreshRequest:
      properties:
        locker_id:
          type: string
          minLength: 1
          title: Locker Id
      type: object
      required:
      - locker_id
      title: RefreshRequest
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    ViewerTokenRequest:
      properties:
        locker_id:
          type: string
          minLength: 1
          title: Locker Id
        filename:
          type: string
          maxLength: 255
          minLength: 1
          title: Filename
        ttl_minutes:
          type: integer
          maximum: 120.0
          minimum: 1.0
          title: Ttl Minutes
          default: 30
      type: object
      required:
      - locker_id
      - filename
      title: ViewerTokenRequest
    Receipt:
      properties:
        receipt_id:
          type: string
          title: Receipt Id
        paid_amount:
          type: string
          title: Paid Amount
          description: Human-readable payment amount in the pay asset (e.g. "0.001")
        paid_raw:
          type: integer
          title: Paid Raw
          description: Payment amount in atomic units (lamports for SOL, wei for EVM)
        pay_asset:
          type: string
          title: Pay Asset
          description: Payment asset identifier (e.g. "SOL", "MON", "USDC", "USDT")
        network:
          type: string
          title: Network
          description: Blockchain network (e.g. "solana-devnet", "monad-testnet")
        payer_pubkey:
          type: string
          title: Payer Pubkey
        tx_hash:
          type: string
          title: Tx Hash
        slot:
          anyOf:
          - type: integer
          - type: 'null'
          title: Slot
          description: Solana slot number. Solana only; null for EVM chains.
        block_number:
          anyOf:
          - type: integer
          - type: 'null'
          title: Block Number
          description: EVM block number. EVM only; null for Solana.
        sig_alg:
          type: string
          title: Sig Alg
          description: 'Signature algorithm: "ed25519" (Solana) or "secp256k1" (EVM)'
          default: ed25519
        units:
          type: integer
          title: Units
        provider:
          type: string
          title: Provider
        created_at:
          type: string
          format: date-time
          title: Created At
      type: object
      required:
      - receipt_id
      - paid_amount
      - paid_raw
      - pay_asset
      - network
      - payer_pubkey
      - tx_hash
      - sig_alg
      title: Receipt
      description: Multi-chain payment receipt. Supports Solana (ed25519) and EVM (secp256k1) networks.
    VerifyPaymentResponse:
      properties:
        verified:
          type: boolean
          title: Verified
        received_amount:
          type: string
          title: Received Amount
          description: Human-readable amount received on-chain
        received_raw:
          type: integer
          title: Received Raw
          description: Amount received in atomic units (lamports/wei)
        pay_asset:
          type: string
          title: Pay Asset
          description: Asset used for payment (e.g. "SOL", "MON")
        amount_match:
          type: boolean
          title: Amount Match
          description: True if received_amount >= paid_amount
        payer_match:
          type: boolean
          title: Payer Match
        slot_match:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Slot Match
          description: Solana only; null for EVM
        block_match:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Block Match
          description: EVM only; null for Solana
      type: object
      required:
      - verified
      - received_amount
      - received_raw
      - pay_asset
      - amount_match
      - payer_match
      title: VerifyPaymentResponse
      description: Multi-chain payment verification result.
paths:
  /v1/storage/signed_provision:
    post:
      summary: Signed Storage Provision
      operationId: signed_storage_provision_v1_storage_signed_provision_post
      parameters:
      - name: X-Nukez-Envelope
        in: header
        required: true
        schema:
          type: string
          title: X-Nukez-Envelope
      - name: X-Nukez-Signature
        in: header
        required: true
        schema:
          type: string
          title: X-Nukez-Signature
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProvisionRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/lockers/{locker_id}/record:
    get:
      tags:
      - lockers_v1
      summary: Locker Record
      operationId: locker_record_v1_lockers__locker_id__record_get
      parameters:
      - name: locker_id
        in: path
        required: true
        schema:
          type: string
          title: Locker Id
      - name: X-Nukez-Envelope
        in: header
        required: true
        schema:
          type: string
          title: X-Nukez-Envelope
      - name: X-Nukez-Signature
        in: header
        required: true
        schema:
          type: string
          title: X-Nukez-Signature
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/lockers/{locker_id}/urls:
    get:
      tags:
      - lockers_v1
      summary: Locker Urls
      operationId: locker_urls_v1_lockers__locker_id__urls_get
      parameters:
      - name: locker_id
        in: path
        required: true
        schema:
          type: string
          title: Locker Id
      - name: X-Nukez-Envelope
        in: header
        required: true
        schema:
          type: string
          title: X-Nukez-Envelope
      - name: X-Nukez-Signature
        in: header
        required: true
        schema:
          type: string
          title: X-Nukez-Signature
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/lockers/{locker_id}/files:
    post:
      tags:
      - files
      summary: Create File
      operationId: create_file_v1_lockers__locker_id__files_post
      parameters:
      - name: locker_id
        in: path
        required: true
        schema:
          type: string
          title: Locker Id
      - name: X-Nukez-Envelope
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Nukez-Envelope
      - name: X-Nukez-Signature
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Nukez-Signature
      - name: Authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateFileRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    get:
      tags:
      - files
      summary: List Files
      operationId: list_files_v1_lockers__locker_id__files_get
      parameters:
      - name: locker_id
        in: path
        required: true
        schema:
          type: string
          title: Locker Id
      - name: X-Nukez-Envelope
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Nukez-Envelope
      - name: X-Nukez-Signature
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Nukez-Signature
      - name: Authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/lockers/{locker_id}/files/batch:
    post:
      tags:
      - files
      summary: Create Files Batch
      description: 'Create multiple file entries and return short URL pairs in one call.


        This is the canonical bulk primitive for SDK/MCP upload workflows.'
      operationId: create_files_batch_v1_lockers__locker_id__files_batch_post
      parameters:
      - name: locker_id
        in: path
        required: true
        schema:
          type: string
          title: Locker Id
      - name: X-Nukez-Envelope
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Nukez-Envelope
      - name: X-Nukez-Signature
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Nukez-Signature
      - name: Authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchCreateFileRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/lockers/{locker_id}/files/{filename}:
    get:
      tags:
      - files
      summary: Get File
      operationId: get_file_v1_lockers__locker_id__files__filename__get
      parameters:
      - name: locker_id
        in: path
        required: true
        schema:
          type: string
          title: Locker Id
      - name: filename
        in: path
        required: true
        schema:
          type: string
          title: Filename
      - name: ttl_min
        in: query
        required: false
        schema:
          type: integer
          maximum: 1440
          minimum: 1
          default: 30
          title: Ttl Min
      - name: X-Nukez-Envelope
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Nukez-Envelope
      - name: X-Nukez-Signature
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Nukez-Signature
      - name: Authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    delete:
      tags:
      - files
      summary: Delete File
      operationId: delete_file_v1_lockers__locker_id__files__filename__delete
      parameters:
      - name: locker_id
        in: path
        required: true
        schema:
          type: string
          title: Locker Id
      - name: filename
        in: path
        required: true
        schema:
          type: string
          title: Filename
      - name: X-Nukez-Envelope
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Nukez-Envelope
      - name: X-Nukez-Signature
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Nukez-Signature
      - name: Authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/lockers/{locker_id}/files/urls:
    post:
      tags:
      - files
      summary: Batch Download Urls
      description: "Generate signed download URLs for multiple files in one call.\n\nOne signed envelope, one API round-trip, N download URLs back.\nDesigned for batch download workflows where per-file URL generation\nwould trigger rate limits.\n\nAuth: Signed envelope.\n\nBody:\n    filenames: [\"a.txt\", \"b.txt\", ...]\n    ttl_min: 30  (optional, default 30)\n\nResponse:\n    {\n        \"locker_id\": \"locker_abc123\",\n        \"urls\": [\n            {\n                \"filename\": \"a.txt\",\n                \"download_url\": \"https://...\",\n                \"content_type\": \"text/plain\",\n                \"content_hash\": \"sha256:...\",\n                \"size_bytes\": 1234\n            },\n            ...\n        ],\n        \"found\": 3,\n        \"not_found\": [\"missing.txt\"],\n        \"urls_expire_in_sec\": 1800\n    }"
      operationId: batch_download_urls_v1_lockers__locker_id__files_urls_post
      parameters:
      - name: locker_id
        in: path
        required: true
        schema:
          type: string
          title: Locker Id
      - name: X-Nukez-Envelope
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Nukez-Envelope
      - name: X-Nukez-Signature
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Nukez-Signature
      - name: Authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchUrlsRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'