{"openapi":"3.0.3","info":{"title":"Cryonia API","version":"1.0.0","description":"Cryopreserved specimens & ancient-DNA database. Frozen Ice-Age animals\npreserved in permafrost and glaciers — mammoths, horses, rhinoceros,\nand other megafauna with soft tissue intact.\n\nCryonia is the **non-fossilised** complement to GBIF (modern species) and\nPBDB (fossils). Specimens have known discovery coordinates, age (years\nBefore Present), preservation quality, and, where extracted, ancient-DNA\nfragments. Paleoecology is enriched via the Ecology AI integration.\n","contact":{"name":"Cryonia API Support","email":"support@cryonia.org"},"license":{"name":"CC-BY-4.0","url":"https://creativecommons.org/licenses/by/4.0/"}},"servers":[{"url":"https://api.cryonia.org","description":"Production server"},{"url":"http://localhost:8787","description":"Local development"}],"security":[{"ApiKeyAuth":[]}],"paths":{"/":{"get":{"summary":"API root information","operationId":"getRoot","tags":["System"],"security":[],"responses":{"200":{"description":"API information"}}}},"/health":{"get":{"summary":"Health check","operationId":"getHealth","tags":["System"],"security":[],"responses":{"200":{"description":"Service healthy"}}}},"/api/v1":{"get":{"summary":"API v1 root — directory of available cryopreservation endpoints.","description":"Returns a directory of the v1 endpoints under this API along with\ntheir parameters, useful for clients that want to enumerate\ncapabilities programmatically.\n","operationId":"getApiV1Root","tags":["System"],"security":[],"responses":{"200":{"description":"API v1 directory"}}}},"/v1/metadata/enums":{"get":{"summary":"List every enum used by the Cryonia API.","description":"Returns the directory of enums (preservation_quality, taxon, data_source,\nlanguage) with localised labels in the caller's language.\n","operationId":"listEnums","tags":["Metadata"],"security":[],"responses":{"200":{"description":"Enum metadata"}}}},"/v1/metadata/enums/{name}":{"get":{"summary":"Get one Cryonia enum (preservation_quality, taxon, data_source) by name.","operationId":"getEnum","description":"Returns localised values for one enum. See `listEnums` for the\ndirectory of available enum names.\n","tags":["Metadata"],"security":[],"parameters":[{"name":"name","in":"path","required":true,"example":"preservation_quality","schema":{"type":"string"}}],"responses":{"200":{"description":"Enum values"}}}},"/api/v1/specimens":{"get":{"summary":"List or search cryopreserved specimens.","description":"Returns the paginated list of cryopreserved specimens with their\ncommon name, scientific name, age (years Before Present), and\ndiscovery location. Supports free-text search via `q` (matches\nscientific name and common name in en/ja/ru).\n","operationId":"listSpecimens","tags":["Specimens"],"security":[],"parameters":[{"name":"q","in":"query","required":false,"description":"Free-text search (matches scientific or common name).","example":"mammoth","schema":{"type":"string","minLength":2}},{"name":"lang","in":"query","required":false,"description":"Language for common name (ISO 639-1).","schema":{"type":"string","enum":["en","ja","ru"],"default":"en"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":20,"maximum":100}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","default":0}}],"responses":{"200":{"description":"Specimens (with pagination)","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"count":{"type":"integer"},"results":{"type":"array","items":{"$ref":"#/components/schemas/Specimen"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}}}}}}}},"/api/v1/specimens/stats/summary":{"get":{"summary":"Aggregate statistics across the specimens collection.","description":"Returns counts grouped by taxon, preservation quality, age range,\nand discovery location. Useful for dashboards and at-a-glance\ncoverage assessment.\n","operationId":"getSpecimenStatsSummary","tags":["Specimens"],"security":[],"responses":{"200":{"description":"Specimen aggregate statistics"}}}},"/api/v1/specimens/{id}":{"get":{"summary":"Get a single specimen's full record (with publications, images).","description":"Returns the complete record for one specimen — taxonomy, age,\npreservation method, dimensions, storage location, related\npublications (DOI), and images. Use after `listSpecimens` to drill\ninto a specific record.\n","operationId":"getSpecimen","tags":["Specimens"],"security":[],"parameters":[{"name":"id","in":"path","required":true,"description":"Specimen UUID.","example":"abc-123","schema":{"type":"string"}}],"responses":{"200":{"description":"Specimen detail","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"$ref":"#/components/schemas/SpecimenDetail"}}}}}},"404":{"$ref":"#/components/responses/NotFound"}}}},"/api/v1/dna":{"get":{"summary":"List ancient-DNA fragments extracted from cryopreserved specimens.","description":"Returns the catalogue of aDNA fragments — sequence ID, source\nspecimen, gene/locus, sequencing platform, and quality metrics.\nUse for ancient-DNA studies, phylogenetic comparisons, and\ncross-referencing with modern reference genomes.\n","operationId":"listDnaFragments","tags":["aDNA"],"security":[],"parameters":[{"name":"specimen_id","in":"query","required":false,"description":"Filter to fragments from one specimen.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":20,"maximum":100}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","default":0}}],"responses":{"200":{"description":"aDNA fragment list"}}}},"/api/v1/dna/stats/summary":{"get":{"summary":"Aggregate statistics across the ancient-DNA fragment catalogue.","description":"Returns counts grouped by source specimen, gene/locus, sequencing\nplatform, and quality tier.\n","operationId":"getDnaStatsSummary","tags":["aDNA"],"security":[],"responses":{"200":{"description":"aDNA aggregate statistics"}}}},"/api/v1/dna/{id}":{"get":{"summary":"Get a single aDNA fragment's record (sequence, provenance).","description":"Returns the full record for one aDNA fragment — base sequence (or\naccess reference for large sequences), source specimen, locus,\nsequencing methodology, and quality metrics.\n","operationId":"getDnaFragment","tags":["aDNA"],"security":[],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"aDNA fragment detail"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/api/v1/fossils/{taxonName}/paleoecology":{"get":{"summary":"Get paleoecological insights for a taxon (Ecology AI).","description":"Retrieves paleoecological insights inferred from modern relatives —\ntrophic level, social behaviour, ecological role, predators / prey /\ncompetitors / mutualists. Powered by Ecology AI integration.\n","operationId":"getFossilPaleoecology","tags":["Ecology AI"],"security":[],"parameters":[{"name":"taxonName","in":"path","required":true,"description":"Taxon name in `Genus_species` form.","example":"Mammuthus_primigenius","schema":{"type":"string"}}],"responses":{"200":{"description":"Paleoecological data"}}}},"/api/v1/fossils/{taxonName}/paleoecology/summary":{"get":{"summary":"Summary statistics from the paleoecology literature for a taxon.","description":"Returns aggregate paleoecology statistics — total papers, total\nrecorded interactions, by-type breakdown — drawn from scientific\nliterature for the requested taxon.\n","operationId":"getFossilPaleoecologySummary","tags":["Ecology AI"],"security":[],"parameters":[{"name":"taxonName","in":"path","required":true,"example":"Mammuthus_primigenius","schema":{"type":"string"}}],"responses":{"200":{"description":"Paleoecology summary statistics"}}}}},"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key","description":"API key sent via header (X-API-Key). Obtain from the PPN Hub developer portal."}},"schemas":{"Specimen":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"specimen_code":{"type":"string","example":"LENA-FOAL-2018"},"scientific_name":{"type":"string","example":"Equus caballus"},"common_name":{"type":"object","properties":{"en":{"type":"string"},"ja":{"type":"string"},"ru":{"type":"string"}}},"taxonomy":{"type":"object","properties":{"kingdom":{"type":"string"},"phylum":{"type":"string"},"class":{"type":"string"},"order":{"type":"string"},"family":{"type":"string"},"genus":{"type":"string"},"species":{"type":"string"}}},"age_bp":{"type":"integer","description":"Age in years Before Present"},"discovery_location":{"type":"string"},"discovery_year":{"type":"integer"},"preservation_quality":{"type":"string","enum":["excellent","good","fair","poor"]},"soft_tissue_preserved":{"type":"boolean"},"dna_extracted":{"type":"boolean"},"permafrost_preserved":{"type":"boolean"}}},"SpecimenDetail":{"allOf":[{"$ref":"#/components/schemas/Specimen"},{"type":"object","properties":{"description":{"type":"string"},"discovery_details":{"type":"string"},"coordinates":{"type":"object","properties":{"lat":{"type":"number"},"lon":{"type":"number"}}},"preservation_method":{"type":"string"},"storage_location":{"type":"string"},"research_institutions":{"type":"array","items":{"type":"string"}},"publications":{"type":"array","items":{"type":"object","properties":{"title":{"type":"string"},"authors":{"type":"string"},"year":{"type":"integer"},"doi":{"type":"string"}}}},"images":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string"},"caption":{"type":"string"},"license":{"type":"string"}}}}}}]},"Pagination":{"type":"object","properties":{"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"},"has_more":{"type":"boolean"}}},"ErrorResponse":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string"},"message":{"type":"string"}}}},"responses":{"NotFound":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"BadRequest":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"tags":[{"name":"System","description":"Health and root metadata."},{"name":"Specimens","description":"Cryopreserved specimen records and statistics."},{"name":"aDNA","description":"Ancient-DNA fragments extracted from specimens."},{"name":"Ecology AI","description":"Paleoecology insights powered by Ecology AI."},{"name":"Metadata","description":"Localised enum lookups."}]}