Declare a source upload
Creates a tenant-bound pending upload identity for exact source bytes MeshQu will hold.
RECORDS that this tenant declared an upload of a given length and digest, and who declared it.
ESTABLISHES NOTHING ABOUT ANY BYTES. No bytes exist yet. This record is not a source manifest item and not a review subject, and its existence is not a custody claim.
The declaration is FROZEN here. It cannot be restated once bytes arrive, which is what makes the check on upload a comparison of two independently produced values rather than a value against itself.
Custody is MeshQu-controlled: the bytes are held by MeshQu, tenant-scoped, at a content address that includes the tenant. Availability is later reported as a CHECKED OBSERVATION, made at a moment, never as a standing guarantee.
Authorizations
MeshQu API key passed as a bearer token: Authorization: Bearer mqu_…. Mint one in the console (Settings → API keys).
Tenant UUID for multi-tenant isolation. Required on all authenticated routes — validated before authentication (middleware/tenant.ts), so a missing or non-UUID header returns 400 (MISSING_TENANT_ID / INVALID_TENANT_ID) before the API key is checked.
Body
SHA-256 as 64 lowercase hexadecimal characters.
^[0-9a-f]{64}$Exact number of octets you are about to upload. Also frozen.
x >= 0IANA media type of the bytes. Recorded; not sniffed or validated.
1 - 255Response
Default Response
PENDING (created, no bytes), STAGED (bytes received and checked against the frozen declaration), FINALISED (an object exists at its content address and was read back and re-hashed), ABANDONED (terminal; abandon_reason says why). FINALISED IS NOT SEALED: a finalised object that no review submission references is an orphan and bounded reconciliation will collect it.
PENDING sha256/raw SHA-256 as 64 lowercase hexadecimal characters.
^[0-9a-f]{64}$x >= 0Digest of what actually arrived. Null before any bytes are received.
^[0-9a-f]{64}$x >= 0The object now holding the bytes. Set only in FINALISED.
Why the upload will not proceed. DECLARED_* means the bytes you sent are not what you said you would send; READ_BACK_* means the store did not return what it was given, which is a storage-integrity fault and not a caller error. They are separate values because an operator looks in different places for each.
DECLARED_LENGTH_MISMATCH