{"openapi":"3.0.3","info":{"title":"FaunaUnify API","version":"1.0.0","description":"Unified Animal Knowledge Database API\n\nFaunaUnify provides integrated animal data across geological time periods, combining fossil records (PBDB),\nmodern species (GBIF), and archaeological data. Focus on Ice Age fauna, extinction events, and evolutionary timelines.\n\n## Features\n- Time period-based fauna search (Ice Age, Pleistocene, etc.)\n- Extinct and extant species integration\n- PBDB + GBIF data unification\n- Geological time metadata\n- Multiple data source support\n- Archaeological layer preparation (Ötzi, zooarchaeology)\n","contact":{"name":"FaunaUnify Support","email":"support@faunaunify.org"},"license":{"name":"MIT License","url":"https://opensource.org/licenses/MIT"}},"servers":[{"url":"https://api.faunaunify.org","description":"Production server"},{"url":"http://localhost:3043","description":"Local development"}],"paths":{"/":{"get":{"summary":"FaunaUnify API root — service info banner.","description":"Returns the FaunaUnify service banner with version, scope, and a directory of top-level resource families.\n","tags":["General"],"security":[],"responses":{"200":{"description":"Service information"}},"operationId":"getRoot"}},"/health":{"get":{"summary":"Health check.","description":"Returns 200 when the service is healthy.\n","tags":["General"],"security":[],"responses":{"200":{"description":"Service healthy"}},"operationId":"getHealth"}},"/fauna/period/{period}":{"get":{"summary":"List fauna species native to one geological period (e.g., Cretaceous).","description":"Returns the species catalogue for a named geological period — Cambrian, Devonian, Cretaceous, Holocene, etc. Use for paleontology timelines and taxon-by-period exploration.\n","tags":["Fauna"],"security":[],"parameters":[{"name":"period","in":"path","required":true,"schema":{"type":"string","enum":["Pleistocene","Holocene","Pliocene","Miocene","Quaternary"]},"description":"Period","example":"Pleistocene"},{"name":"limit","in":"query","schema":{"type":"integer","default":20},"description":"Maximum number of results to return","example":20}],"responses":{"200":{"description":"List of fauna from period","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Fauna"}}}}}}}},"operationId":"getFaunaPeriodPeriod"}},"/fauna/extinct":{"get":{"summary":"Search the extinct-fauna catalogue (taxonomy + extinction context).","description":"Returns extinct species records with last-known-occurrence year, extinction cause, and source citations. Sourced from PBDB, IUCN historical records, and curated extinction lists.\n","tags":["Fauna"],"security":[],"parameters":[{"name":"period","in":"query","schema":{"type":"string"},"description":"Period","example":"Holocene"},{"name":"limit","in":"query","schema":{"type":"integer","default":50},"description":"Maximum number of results to return","example":20}],"responses":{"200":{"description":"List of extinct species"}},"operationId":"getFaunaExtinct"}},"/fauna/extant":{"get":{"summary":"Search the extant (living) fauna catalogue.","description":"Returns currently-living animal species with conservation status, taxonomy, and native range. Sourced from GBIF and IUCN Red List.\n","tags":["Fauna"],"security":[],"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","default":50},"description":"Maximum number of results to return","example":20}],"responses":{"200":{"description":"List of extant species"}},"operationId":"getFaunaExtant"}},"/fauna/advanced-period":{"get":{"summary":"Advanced period search with arbitrary time-range (Ma BP).","description":"Returns species that lived within a custom million-years-ago time range. More flexible than `getFaunaPeriodPeriod` (which uses named periods only). Useful for cross-boundary studies.\n","tags":["Fauna"],"security":[],"parameters":[{"name":"epoch","in":"query","schema":{"type":"string"},"description":"Epoch","example":"Pleistocene"},{"name":"period","in":"query","schema":{"type":"string"},"description":"Period","example":"Quaternary"},{"name":"era","in":"query","schema":{"type":"string"},"description":"Era","example":"Cenozoic"},{"name":"startMa","in":"query","schema":{"type":"number"},"description":"Start time in million years ago","example":2.58},{"name":"endMa","in":"query","schema":{"type":"number"},"description":"End ma","example":0.012},{"name":"limit","in":"query","schema":{"type":"integer"},"description":"Maximum number of results to return","example":20}],"responses":{"200":{"description":"Filtered fauna results"}},"operationId":"getFaunaAdvancedPeriod"}},"/fauna/timeline":{"get":{"summary":"Get the evolutionary timeline for one taxon.","description":"Returns the evolutionary timeline (first appearance, peak, last appearance) for a taxon along with its descendants and relatives. Useful for phylogeny visualisations.\n","tags":["Fauna"],"security":[],"parameters":[{"name":"taxonName","in":"query","required":true,"schema":{"type":"string"},"description":"Taxon name","example":"Mammuthus"},{"name":"startMa","in":"query","schema":{"type":"number"},"description":"Start ma","example":5},{"name":"endMa","in":"query","schema":{"type":"number"},"description":"End ma","example":0.01}],"responses":{"200":{"description":"Evolutionary timeline data"}},"operationId":"getFaunaTimeline"}},"/fauna/{id}":{"get":{"summary":"Get the full record for one fauna species by ID.","description":"Returns the complete FaunaUnify record for one species — taxonomy, geological range, conservation status, native range polygon, related publications, and aDNA links (when available via Cryonia).\n","tags":["Fauna"],"security":[],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Unique resource identifier","example":"abc-123"}],"responses":{"200":{"description":"Detailed fauna data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FaunaDetail"}}}}},"operationId":"getFaunaId"}},"/fauna/{taxonName}/interactions":{"get":{"summary":"Get species interactions (Ecology AI)","description":"Retrieve documented species interactions from scientific literature.\nPowered by Ecology AI - extracts predation, competition, mutualism, and other ecological relationships.\n","tags":["Ecology AI Integration"],"security":[],"parameters":[{"name":"taxonName","in":"path","required":true,"schema":{"type":"string"},"description":"Scientific name of the species","example":"Panthera tigris"}],"responses":{"200":{"description":"Species interaction data","content":{"application/json":{"schema":{"type":"object","properties":{"taxon":{"type":"string","example":"Panthera tigris"},"total_interactions":{"type":"integer","example":12},"interactions":{"type":"array","items":{"type":"object","properties":{"subject_species":{"type":"string"},"object_species":{"type":"string"},"interaction_type":{"type":"string","enum":["predation","competition","mutualism","parasitism","herbivory"]},"confidence":{"type":"number"},"evidence":{"type":"string"},"source_count":{"type":"integer"}}}},"source":{"type":"string","example":"ecology-ai"},"status":{"type":"string","enum":["available","unavailable","error"]}}}}}},"404":{"description":"Species not found"}},"operationId":"getFaunaTaxonNameInteractions"}},"/fauna/{taxonName}/interactions/summary":{"get":{"summary":"Get interaction statistics (Ecology AI)","description":"Summary statistics for species interactions from scientific literature","tags":["Ecology AI Integration"],"security":[],"parameters":[{"name":"taxonName","in":"path","required":true,"schema":{"type":"string"},"description":"Scientific name of the species","example":"Canis_lupus"}],"responses":{"200":{"description":"Interaction summary statistics","content":{"application/json":{"schema":{"type":"object","properties":{"taxon":{"type":"string"},"summary":{"type":"object","properties":{"total_papers":{"type":"integer"},"total_interactions":{"type":"integer"},"by_type":{"type":"array"}}},"status":{"type":"string"}}}}}}},"operationId":"getFaunaTaxonNameInteractionsSummary"}}},"components":{"schemas":{"Fauna":{"type":"object","properties":{"id":{"type":"string"},"sources":{"type":"array","items":{"type":"string","enum":["pbdb","gbif","arch","iucn","bold"]}},"scientificName":{"type":"string"},"kingdom":{"type":"string"},"phylum":{"type":"string"},"class":{"type":"string"},"order":{"type":"string"},"family":{"type":"string"},"genus":{"type":"string"},"species":{"type":"string"},"isExtinct":{"type":"boolean"},"earliestAge":{"type":"number"},"latestAge":{"type":"number"},"geologicalEra":{"type":"string"},"geologicalPeriod":{"type":"string"},"geologicalEpoch":{"type":"string"},"vernacularNames":{"type":"object","properties":{"ja":{"type":"array","items":{"type":"string"}},"en":{"type":"array","items":{"type":"string"}}}}}},"FaunaDetail":{"allOf":[{"$ref":"#/components/schemas/Fauna"},{"type":"object","properties":{"description":{"type":"string"},"habitat":{"type":"string"},"diet":{"type":"string"},"pbdbTaxonId":{"type":"integer"},"gbifTaxonKey":{"type":"integer"},"images":{"type":"array","items":{"type":"object"}}}}]}},"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key","description":"API key for authentication. Obtain from the PPN Hub developer portal."}}},"tags":[{"name":"General"},{"name":"Fauna"}],"security":[{"ApiKeyAuth":[]}]}