vault

Open an upload session, or upload small objects inline in one call

Declares the expected manifest (kinds, ids, FULL_OBJECT SHA-256, sizes) and returns one create-only presigned PUT per object. Each URL signs If-None-Match: *, the exact Content-Length, and the exact x-amz-checksum-sha256 — send headers verbatim or storage rejects the write, so an upload can neither overwrite an existing object nor store bytes that do not hash to what you declared. URLs are returned once: re-reading the session redacts them. The session reserves its accounted bytes (64 KiB per-object floor) against the ORGANIZATION's pooled storage. An object id already present in any state is refused — the row is the tombstone.

Inline upload (vault-composite-state-read design D2): when EVERY entry also carries bytes (base64url) at or under 256 KiB, and the request's decoded total is at or under 1 MiB, the gateway verifies each declared checksum against the received bytes BEFORE any write and performs the storage writes itself — create-only, same checksum binding, same accounting — and the response IS the finalize response (receipts, charged_bytes, finalized_at, deduplicated) instead of presigned PUTs, replacing session + N PUTs + finalize with one call. Mixing inline and presigned entries in one request is refused VALIDATION_FAILED; an object over either cap uses the presigned shape unchanged.

post/vaults/v1/{vault_id}/upload-sessions

Request

  • Base URL: https://api.run402.com
  • URL: https://api.run402.com/vaults/v1/{vault_id}/upload-sessions
  • Auth: one of:
    • API key in header SIGN-IN-WITH-X
    • HTTP bearer
    • HTTP bearer

Path parameters

vault_idstring required

The vault id (src_<32 hex>); the wire field is repo_id (protocol D185).

Headers

SIGN-IN-WITH-Xstring required

SIWX auth header — base64-encoded JSON payload containing a signed CAIP-122 (EIP-4361) message. See https://docs.x402.org/extensions/sign-in-with-x.

Request body

Response

Session opened; presigned PUTs returned once

upload_session_idstring uuid
repo_idstring
lease_expires_atstring date-time
reserved_bytesstring

Decimal byte count as a string (values exceed 2^53).

next_actionsobject[]
receiptsobject[]

Inline upload only: present INSTEAD of the fields above — this response IS the finalize response (design D2). See POST .../finalize for the receipt shape.

charged_bytesstring

Inline upload only. Decimal byte count as a string.

finalized_atstring date-time

Inline upload only.

deduplicatedboolean

Inline upload only — always false for a freshly created session's own first (and only) finalize.

Changes

No recorded changes to this operation across all 1 revision of this API.