Scientific depositions
Publishing, verifying, citing, correcting and withdrawing depositions. Back to the documentation home.
Publishing
A curator first registers the institution whose namespace holds the accessions. Use POST /api/institutions with a code such as EXU and the institution name. Add the index_herbariorum_code and ror_id where they exist, so citations resolve to a known institution. GET /api/institutions lists registered codes. A code, Index Herbariorum code or ROR ID cannot be reassigned to another institution.
- An authenticated researcher creates a draft with
POST /api/depositions. Supply a registered institution code, then add the title, license and contributor names and roles, with an optionalorcidfor each contributor. Selectprofile_idsfor analytical profiles,preparation_idsfor samples and preparations deposited without analytical runs (for example an extract tested only in a bioassay, or an essential oil reported by its yield),specimen_idsfor vouchers cited on their own, or any combination. A preparation's sample provenance and linked vouchers are included; a preparation cannot also be included through one of its selected runs. Description and rights statements are optional. Ex Herbario reserves an accession in that institution's namespace. UsePUT /api/depositions/{id}/draftwith the returneddraft_revisionasexpected_revisionto edit. - Review
GET /api/depositions/{id}/draft/previewbefore release. It shows the exact proposed public snapshot. Profiles and preparations must belong to studies available to the draft owner. The preview'sreleaseslists the studies, runs and vouchers that are still private: publishing releases them in the same step, so the curator's approval of the preview covers them (vouchers keep their public-locality setting). It also lists, asalso_public_runs, runs outside the deposition that are already marked released and that these releases would make visible (for example another run of a study that is still private). The preview'sreleases_sha256covers both lists; send it withPOST …/publish, which is refused if anything to be released or made public has changed. A record that was released and later withdrawn is refused until a curator releases it again. Essential-oil preparations need their yield before publishing. The preview uses the voucher's approved regional projection and keeps verbatim labels, exact locations, original sample collection-event text, and account IDs private. Scientific determiner and collector names are included only when the draft enablesinclude_determiner_namesorinclude_collector_names. Collector numbers and type status are always included. Review contributor names and remaining free text before approval. - A curator calls
POST /api/depositions/{id}/publishwith the preview'sdraft_revisionandsnapshot_sha256. If the underlying records or files have changed, review a new preview. Retry the same request to get the same version. The returnedidentifieris the version's public page underPUBLIC_BASE_URL, andurlis its JSON record.
Each published version freezes the metadata, voucher determination, sample and preparation links, methods, measurements, credits, rights, and file digests. It stores a bounded copy of each source file with the snapshot in the database, in the same transaction. The original uploads remain in local storage. Exports of legacy sources are marked legacy-reconstructed. Published files remain available if live records or files later change.
Share the public page at /depositions/{institution}/{accession}/versions/{number}. It shows the citation, licenses and credits, voucher and sample relationships, methods, files, and any correction or withdrawal notice. The Download version ZIP link packages the frozen deposition.json, source files under files/, and a versioned manifest.json with sizes and SHA-256 digests. Later DOI links and status notices appear on the page while the archived version bytes stay fixed. Withdrawal disables downloads for that version.
Verify a downloaded ZIP from a checkout with Python 3.12. Use the snapshot SHA-256 shown on the public page to compare against the published digest.
python -m app.deposition.verify_archive .\deposition-v1.zip --snapshot-sha256 <digest>
The verifier runs offline without the server, database, or installed Python dependencies. Omitting the expected digest still checks the archive's internal consistency.
- Get a dataset DOI by mirroring the version to Zenodo. Set
ZENODO_TOKENto a token with thedeposit:writeanddeposit:actionsscopes. Rehearse withZENODO_URL=https://sandbox.zenodo.org, then runpython -m app.deposition.mirror_zenodo EXU <accession> 1 --curator curator@example.org. Add--dry-runto review the Zenodo metadata first. Zenodo receives the same ZIP that Ex Herbario serves, and Ex Herbario records the DOI it returns. An institution with its own DataCite membership can register a DOI fromGET /api/depositions/public/{institution}/{accession}/versions/{number}/datacite.json. Record that DOI withPUT /api/depositions/{id}/versions/{number}/doiand{"doi": "10.…", "agency": "datacite"}. The public page then cites the DOI. - Link a bare article DOI with
PUT /api/depositions/{id}/versions/{number}/article-doi. Article links are attached to the cited version without editing its snapshot. - Create a correction by sending a complete new draft with
expected_revision: nulland acorrection_reason, then preview and publish it. The accession stays the same and the version-specific URL changes. Earlier versions remain citable and indicate that they were superseded. - Withdraw a published version with
POST /api/depositions/{id}/versions/{number}/withdrawand a publicreason. Its URL returns a 410 notice with citation identity and linked DOIs. File downloads are withdrawn and the frozen records remain in the archive. Withdrawing release from a live voucher or profile leaves the immutable deposition in place. Use the version withdrawal action for the published record.