{"openapi":"3.1.0","info":{"title":"mythdex","version":"0.1.0","description":"Source-cited Korean mythical creatures. Every creature carries at least one attestation (source, locator, URL). Code MIT, data CC BY 4.0.","license":{"name":"CC-BY-4.0 (data)","identifier":"CC-BY-4.0"}},"servers":[{"url":"https://mythdex.nante.app"}],"paths":{"/v1":{"get":{"summary":"API index and data version","responses":{"200":{"description":"Index","content":{"application/json":{"schema":{"type":"object"}}}},"304":{"description":"Not modified (the If-None-Match ETag equals the current data version)."},"400":{"$ref":"#/components/responses/Error"}}}},"/v1/creatures":{"get":{"summary":"List creatures (paged)","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"offset","in":"query","schema":{"type":"integer","minimum":0,"default":0}},{"name":"lang","in":"query","description":"all keeps every {ko, en} pair; ko or en collapses each pair to one string (en falls back to ko).","schema":{"type":"string","enum":["all","ko","en"],"default":"all"}},{"name":"category","in":"query","schema":{"type":"string"}},{"name":"region","in":"query","schema":{"type":"string"}},{"name":"source","in":"query","description":"Only creatures attested by this source id.","schema":{"type":"string"}},{"name":"status","in":"query","schema":{"type":"string","enum":["draft","reviewed"]}},{"name":"sort","in":"query","schema":{"type":"string","enum":["id","name","name-en","earliest"],"default":"id"}}],"responses":{"200":{"description":"A page of creature summaries","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreaturePage"}}}},"304":{"description":"Not modified (the If-None-Match ETag equals the current data version)."},"400":{"$ref":"#/components/responses/Error"}}}},"/v1/creatures/{key}":{"get":{"summary":"One creature by dex id or slug","parameters":[{"name":"key","in":"path","required":true,"description":"Dex id (integer) or slug, e.g. 25 or gumiho.","schema":{"type":"string"}},{"name":"lang","in":"query","description":"all keeps every {ko, en} pair; ko or en collapses each pair to one string (en falls back to ko).","schema":{"type":"string","enum":["all","ko","en"],"default":"all"}}],"responses":{"200":{"description":"The full creature record with linked sources","content":{"application/json":{"schema":{"type":"object"}}}},"304":{"description":"Not modified (the If-None-Match ETag equals the current data version)."},"400":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"}}}},"/v1/random":{"get":{"summary":"A random creature (never cached)","parameters":[{"name":"lang","in":"query","description":"all keeps every {ko, en} pair; ko or en collapses each pair to one string (en falls back to ko).","schema":{"type":"string","enum":["all","ko","en"],"default":"all"}}],"responses":{"200":{"description":"A creature","content":{"application/json":{"schema":{"type":"object"}}}},"304":{"description":"Not modified (the If-None-Match ETag equals the current data version)."},"400":{"$ref":"#/components/responses/Error"}}}},"/v1/search":{"get":{"summary":"Search names, aliases and descriptions","description":"Three or more characters use FTS5 trigram phrase matching; shorter terms use substring matching.","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":1,"maxLength":64}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"offset","in":"query","schema":{"type":"integer","minimum":0,"default":0}},{"name":"lang","in":"query","description":"all keeps every {ko, en} pair; ko or en collapses each pair to one string (en falls back to ko).","schema":{"type":"string","enum":["all","ko","en"],"default":"all"}}],"responses":{"200":{"description":"Matching creature summaries","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreaturePage"}}}},"304":{"description":"Not modified (the If-None-Match ETag equals the current data version)."},"400":{"$ref":"#/components/responses/Error"}}}},"/v1/categories":{"get":{"summary":"All categories","parameters":[{"name":"lang","in":"query","description":"all keeps every {ko, en} pair; ko or en collapses each pair to one string (en falls back to ko).","schema":{"type":"string","enum":["all","ko","en"],"default":"all"}}],"responses":{"200":{"description":"Categories","content":{"application/json":{"schema":{"type":"object"}}}},"304":{"description":"Not modified (the If-None-Match ETag equals the current data version)."},"400":{"$ref":"#/components/responses/Error"}}}},"/v1/categories/{id}":{"get":{"summary":"One category and its creatures","parameters":[{"name":"id","in":"path","required":true,"description":"Category id","schema":{"type":"string"}},{"name":"lang","in":"query","description":"all keeps every {ko, en} pair; ko or en collapses each pair to one string (en falls back to ko).","schema":{"type":"string","enum":["all","ko","en"],"default":"all"}}],"responses":{"200":{"description":"Category","content":{"application/json":{"schema":{"type":"object"}}}},"304":{"description":"Not modified (the If-None-Match ETag equals the current data version)."},"400":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"}}}},"/v1/regions":{"get":{"summary":"All regions","parameters":[{"name":"lang","in":"query","description":"all keeps every {ko, en} pair; ko or en collapses each pair to one string (en falls back to ko).","schema":{"type":"string","enum":["all","ko","en"],"default":"all"}}],"responses":{"200":{"description":"Regions","content":{"application/json":{"schema":{"type":"object"}}}},"304":{"description":"Not modified (the If-None-Match ETag equals the current data version)."},"400":{"$ref":"#/components/responses/Error"}}}},"/v1/regions/{id}":{"get":{"summary":"One region and its creatures","parameters":[{"name":"id","in":"path","required":true,"description":"Region id, e.g. kr","schema":{"type":"string"}},{"name":"lang","in":"query","description":"all keeps every {ko, en} pair; ko or en collapses each pair to one string (en falls back to ko).","schema":{"type":"string","enum":["all","ko","en"],"default":"all"}}],"responses":{"200":{"description":"Region","content":{"application/json":{"schema":{"type":"object"}}}},"304":{"description":"Not modified (the If-None-Match ETag equals the current data version)."},"400":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"}}}},"/v1/sources":{"get":{"summary":"List cited sources (paged)","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"offset","in":"query","schema":{"type":"integer","minimum":0,"default":0}},{"name":"lang","in":"query","description":"all keeps every {ko, en} pair; ko or en collapses each pair to one string (en falls back to ko).","schema":{"type":"string","enum":["all","ko","en"],"default":"all"}}],"responses":{"200":{"description":"A page of sources","content":{"application/json":{"schema":{"type":"object"}}}},"304":{"description":"Not modified (the If-None-Match ETag equals the current data version)."},"400":{"$ref":"#/components/responses/Error"}}}},"/v1/sources/{id}":{"get":{"summary":"One source and every creature it attests, with locators","parameters":[{"name":"id","in":"path","required":true,"description":"Source id","schema":{"type":"string"}},{"name":"lang","in":"query","description":"all keeps every {ko, en} pair; ko or en collapses each pair to one string (en falls back to ko).","schema":{"type":"string","enum":["all","ko","en"],"default":"all"}}],"responses":{"200":{"description":"Source","content":{"application/json":{"schema":{"type":"object"}}}},"304":{"description":"Not modified (the If-None-Match ETag equals the current data version)."},"400":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"}}}}},"components":{"schemas":{"CreatureSummary":{"type":"object","properties":{"id":{"type":"integer"},"slug":{"type":"string"},"name":{"oneOf":[{"type":"string"},{"type":"object","properties":{"ko":{"type":"string"},"en":{"type":"string"}}}]},"category":{"type":"string"},"url":{"type":"string","format":"uri"}}},"CreaturePage":{"type":"object","required":["count","next","previous","results"],"properties":{"count":{"type":"integer"},"next":{"type":["string","null"],"format":"uri"},"previous":{"type":["string","null"],"format":"uri"},"results":{"type":"array","items":{"$ref":"#/components/schemas/CreatureSummary"}}}},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"integer"},"message":{"type":"string"}}}}}},"responses":{"Error":{"description":"A written error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}