--- title: "Shared Shapes" description: "The shapes several endpoints share: the manifest, the published record, the upload outcome, the slot entry and the progress report." published: 2026-09-23T10:54:45.902692+00:00 updated: 2026-09-23T10:54:45.902692+00:00 tags: ["api", "parallax", "reference", "rest"] url: https://xiobjects.com/docs/xio/parallax/rest-api/reference/shapes source: XI Objects --- # Shared Shapes These shapes appear in more than one endpoint of the [REST API Reference](/docs/xio/parallax/rest-api/reference). ### Manifest Returned wherever manifests come back, which is `/records` and nowhere else. | Field | Type | Description | |-------|------|-------------| | `type` | `string` | The kind exactly as stated on the multipart part name. | | `form` | `string` | `json` or `jumbf`. | | `payload` | `object` or `string` | The posted bytes. Inline JSON when `form` is `json`, base64 when `form` is `jumbf`. | | `hash` | `string?` | BLAKE3-256 over this manifest's STORED bytes, lowercase hex. `null` on a record published before manifest signing. | | `signature` | `string?` | Base64 Ed25519 signature by the registrant's leaf key over this manifest's canonical bytes. `null` on a record published before manifest signing. | ### Published record Returned by `GET /records/{originalImageHash}` and inside `POST /records`. | Field | Type | Description | |-------|------|-------------| | `originalImageHash` | `string` | The hash asked for, echoed back. | | `outcome` | `string` | `published`, `noRecordAnswered`, `takenDown`, `refused` or `retry`. | | `manifests` | `array` | Manifests as registered, each with the record's own hash and signature over it. Present only when `published`. | | `verification` | `object` | The material to verify the record. Present only when `published`. | | `failureReason` | `string` | Why this hash was refused. Present only when `refused` or `retry`. | The verification object: | Field | Type | Description | |-------|------|-------------| | `contentHash` | `string` | The hash the record's own signature was taken over. | | `hashAlgorithm` | `string` | The algorithm that produced it. | | `signedAtUtc` | `datetime` | When the record was signed. | | `signature` | `string` | Base64 Ed25519 signature by the registrant's leaf key over `contentHash` hex-decoded. | | `signatureAlgorithm` | `string` | The signature algorithm, for every signature on the record. | | `publicKey` | `string` | Base64 public key every signature on the record verifies against. | | `leafCertificate` | `string` | The signing leaf certificate, PEM. | | `certificateChain` | `array` | The leaf's issuing chain, PEM, in chain order. | | `leafCertificateThumbprint` | `string` | The leaf certificate's thumbprint. | | `trustContext` | `string` | The trust context the leaf was issued under. | | `trustVersion` | `int` | The trust context's version. | | `canonicalVersion` | `int` | The canonicalisation version the manifest and collection signatures were taken under. | | `collectionSignature` | `string?` | Base64 Ed25519 signature over the record's ordered manifest set. `null` on a record that declares none. | A record carries two kinds of attestation, both by the same leaf key and both verified against `publicKey`. **The image.** Verify `signature` from `contentHash`, `signature` and `publicKey` alone. `trustContext` and `trustVersion` are metadata, not inputs. Verifying it proves that this key attested this image. It does not cover the manifests. **The manifests.** Each manifest's `signature` is over `canonicalVersion` as one byte, then `contentHash` hex-decoded, then the manifest's `type` as UTF-8, then its `hash` hex-decoded — each of the three with a uint16 big-endian length in front of it. `collectionSignature` is over the version byte, the length-prefixed content hash, a uint16 count, and each manifest's length-prefixed kind and hash in returned order; it proves the set's membership and order. `hash` is a BLAKE3-256 over the manifest's STORED bytes, which are what a `jumbf` payload returns byte for byte and are NOT what a `json` payload returns — a JSON-native kind is projected back from the stored JUMBF, so its hash is not recomputable from the answer. A record published before manifest signing returns `null` for all three and states a lower `canonicalVersion`. The leaf certificate's subject is the service's own metadata, identical for every registrant's certificate, so it identifies nobody. See [Recover an image's attribution](/docs/xio/parallax/rest-api/records) for how to check each one. ### Upload outcome One per image part, in request order. Answered by `POST /slots/{slotId}/uploads` and `POST /lookup/slots/{lookupSlotId}/queries`. | Field | Type | Description | |-------|------|-------------| | `partIndex` | `int` | 1-based position among the image parts in the request. | | `fileName` | `string?` | The filename declared on the part, if any. | | `accepted` | `bool` | Whether the slot now holds this image. | | `imageHash` | `string?` | SHA-256 of the accepted bytes, lowercase hex. Always `null` on a rejection. | | `rejectionReason` | `string?` | A fixed sentence. `null` when accepted. | | `registrationRemaining` | `int?` | Remaining registration grant. Carried only on a quota rejection. | | `lookupRemaining` | `int?` | Remaining look-up grant. Carried only on a quota rejection. | | `registrationId` | `uuid?` | The already-registered registration, when it is yours. Never populated on a look-up slot. | ### Slot entry One per entry. Answered by both manifest report routes and by the manifest replace route. | Field | Type | Description | |-------|------|-------------| | `imageHash` | `string` | SHA-256 of the entry's bytes, lowercase hex. | | `manifestsHash` | `string?` | Digest of the stored manifest list. `null` when the entry carries none. | | `byteLength` | `long` | The image's byte length. | | `contentType` | `string?` | The content type the part declared. | | `createdAt` | `datetime` | When the entry was first recorded. | | `state` | `string` | `held`, `registered`, `answered`, `failed`, `errata` or `retry`. | | `notRegisteredReason` | `string?` | Why an `errata` entry will never be registered. `null` otherwise. | No manifest body and no image byte is ever returned here. ### Progress Answered by both progress routes. | Field | Type | Description | |-------|------|-------------| | `slotId` | `string` | The slot's id. | | `status` | `string` | `open` or `committed`. | | `counts.total` | `int` | Entries on the slot. | | `counts.held` | `int` | Entries not yet committed. | | `counts.registered` | `int` | Entries registered. Registration slots only. | | `counts.answered` | `int` | Queries that reached a verdict. Look-up slots only. | | `counts.failed` | `int` | Entries that could not be committed. | | `counts.errata` | `int` | Entries that will never be registered. Registration slots only. | | `entries[].imageHash` | `string` | The entry's hash. | | `entries[].state` | `string` | `held`, `registered`, `answered`, `failed`, `errata` or `retry`. | | `entries[].registrationId` | `uuid?` | The registration this entry points at, when it has one. | | `entries[].failureReason` | `string?` | Why the entry failed, or why an errata will not register. | ---