Reserve a document under a policy and receive its upload path.
const url = 'https://example.com/v1/documents';const options = { method: 'POST', headers: { 'Idempotency-Key': 'example', Authorization: 'Bearer <token>', 'Content-Type': 'application/json' }, body: '{"custodian":{"subject":"example"},"expectedDigest":"example","issuingInstitution":"example","label":"example","length":1,"mediaType":"example","policyId":"example"}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url https://example.com/v1/documents \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --header 'Idempotency-Key: example' \ --data '{ "custodian": { "subject": "example" }, "expectedDigest": "example", "issuingInstitution": "example", "label": "example", "length": 1, "mediaType": "example", "policyId": "example" }'Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Header Parameters
Section titled “Header Parameters”The caller’s key for this request. A retry with the same key and body answers the first outcome; another body under the key is refused.
Request Bodyrequired
Section titled “Request Bodyrequired”The body of POST /v1/documents: reserve one document and the upload of
its single version. Size and media type are refused here, before any
byte moves.
object
Who holds the document in custody.
object
An identifier another system issues, written exactly as its issuer gives it.
The digest the content must have, sha256: and 64 lowercase hex.
The issuing institution, when the caller repeats it. The institution recorded is always the caller’s access profile’s; a different value is refused.
A display label the caller chooses. It is stored and returned as written and never used for an authorization decision.
The exact content length in bytes.
The media type the content is declared as; the content PUT must send
exactly this Content-Type.
The document policy the document is held under.
Example generated
{ "custodian": { "subject": "example" }, "expectedDigest": "example", "issuingInstitution": "example", "label": "example", "length": 1, "mediaType": "example", "policyId": "example"}Responses
Section titled “Responses”The operation succeeded.
The answer to a reservation: the document, its version, and where to send the content.
object
One document as its custodian reads it.
object
What the reading caller may do to this document now, in vocabulary order.
The custodian a reservation names: a subject at the configured token issuer.
object
An identifier another system issues, written exactly as its issuer gives it.
The label the reserving caller chose, as written. Untrusted.
The policy a document version was reserved under, frozen at reservation: its id, its authored version, and the digest of its whole authored body.
object
A SHA-256 digest: sha256: followed by 64 lowercase hex digits.
A local identifier: a lowercase letter, then up to 63 lowercase letters, digits, _, or -.
One document version: its declared and verified content, and the one status a client acts on.
object
A SHA-256 digest: sha256: followed by 64 lowercase hex digits.
Reserved, or the reservation lapsed: no content is stored.
Content stored; no standing approval.
Approved under the current verifier binding and releasable.
Approved once, but not releasable now.
The verifier rejected the content.
The custodian asked for removal; the bytes await erasure.
The bytes are erased; the record remains.
When the reservation lapses if no matching content arrived, RFC 3339.
The route the content is sent to with PUT.
Example
{ "document": { "actions": [ "download" ], "version": { "status": "awaiting-content" } }}Headers
Section titled “Headers”The path of the created resource.
A problem: request.invalid.
object
Example
{ "code": "request.invalid", "type": "https://id.registrystack.org/problems/registry-documents/authentication/refused"}A problem: authentication.refused.
object
Example
{ "code": "authentication.refused", "type": "https://id.registrystack.org/problems/registry-documents/authentication/refused"}Headers
Section titled “Headers”The bearer challenge.
A problem: custody.not-permitted, profile.not-authorized.
object
Example
{ "code": "custody.not-permitted", "type": "https://id.registrystack.org/problems/registry-documents/authentication/refused"}A problem: request.method-not-allowed.
object
Example
{ "code": "request.method-not-allowed", "type": "https://id.registrystack.org/problems/registry-documents/authentication/refused"}A problem: idempotency.key-reused.
object
Example
{ "code": "idempotency.key-reused", "type": "https://id.registrystack.org/problems/registry-documents/authentication/refused"}A problem: idempotency.expired.
object
Example
{ "code": "idempotency.expired", "type": "https://id.registrystack.org/problems/registry-documents/authentication/refused"}A problem: request.body-too-large.
object
Example
{ "code": "request.body-too-large", "type": "https://id.registrystack.org/problems/registry-documents/authentication/refused"}A problem: request.unsupported-media-type.
object
Example
{ "code": "request.unsupported-media-type", "type": "https://id.registrystack.org/problems/registry-documents/authentication/refused"}A problem: custody.quota-exceeded, document-policy.unknown, document.content-type-not-allowed, document.too-large, request.unprocessable.
object
Example
{ "code": "custody.quota-exceeded", "type": "https://id.registrystack.org/problems/registry-documents/authentication/refused"}A problem: service.unavailable.
object
Example
{ "code": "service.unavailable", "type": "https://id.registrystack.org/problems/registry-documents/authentication/refused"}Headers
Section titled “Headers”Whole seconds to wait before trying again.